Next i18n Auth Boilerplate

A complete, production-grade Next.js starter with internationalization, authentication, UI components, testing, and more.

• Are you tired of manually managing translation files in your projects?
• Do you want to streamline your internationalization workflow with fully automated tooling?
• Are you looking for a robust, scalable architecture that combines authentication, localization, theming, and type safety — all in one place?
• Would you benefit from a modern stack with built-in support for testing, reusable UI components, and strict typing from end to end?
• Do you want to future-proof your application with a maintainable and extensible codebase?

If so, this boilerplate is for you. Fork it, customize it, and accelerate your development with a solid foundation that eliminates repetitive work and allows you to focus on what really matters — building great products.

---

---

🔥 Preview

Deployment

This project is live and deployed on Vercel! Visit the live demo: Next i18n Auth Boilerplate Live

Features

• ⚡️ Next.js 15: Fast and scalable React framework with App Router.
• 🌍 i18next: Internationalization (i18n) with fully automated typed translations.
• 🔒 Next-Auth v5: Authentication with JWT, OAuth, and social providers.
• 🎨 shadcn/ui: Beautiful accessible components with Tailwind CSS.
• 🛡️ Zod: End-to-end type-safe validation.
• 🚀 TypeScript: 100% typed full-stack application.
• 🌓 Dark Mode: Light/dark mode with system preference.
• 📈 React Query: Powerful data fetching and caching.
• 🧪 Vitest & Playwright: Full testing stack (unit, integration, e2e).

---

Quick Start

Prerequisites

Make sure you have the following installed:

• Node.js >= 18.x
• Yarn (preferred) or npm
• Git

Installation

1. Clone the repository:

   git clone https://github.com/Sayyat/next-i18n-auth.git
   cd next-i18n-auth

2. Install dependencies:

   yarn install

3. Create a .env file in the root directory and add the following environment variables:

   AUTH_URL=http://127.0.0.1:3001
   AUTH_SECRET=<Your Auth Secret>
   NEXT_PUBLIC_API_URL=<Your API URL>
   API_URL=<Your API URL>
   NODE_ENV=development
   NEXT_TELEMETRY_DISABLED=1
   RAPIDAPI_KEY=<Your RapidAPI key>

4. Start the development server:

   yarn dev

   The application will be available at http://localhost:3000.

---

File Structure

You can find the file structure of the project in the File Structure document.

---

How to Use

Authentication

• Sign Up: Use the register modal to create a new account. The backend API handles user registration and returns access and refresh tokens.
• Log In: Use the login modal to authenticate users. Tokens are stored securely, and JWT is decoded for user details.

Localization

• The project uses i18next for localization. See i18next for more details.
• The localization process is fully automated. See Automation for more details.
• Full autocomplete for namespaces and translation keys thanks to auto type generation
• Supported languages: Kazakh, English, and Russian.
• Language can be changed using the dropdown in the header.

Toast Notifications

• Feedback is provided using react-toastify.
• Example: Error messages during authentication or form validation feedback.

Zod Validation

• Zod is used for client-side schema validation for forms.
• Errors are displayed with translations based on the current locale.

---

Customization

Add New Languages

1. Add the new language key in i18n/lib/config.ts: To add French (fr), update the languages array as follows:

   export const languages = ["kk", "ru", "en", "fr"] as const;

2. Generate language files for the new locale: Run smart-i18n or yarn si command to generate the template language files for the newly added language (fr in this case).

3. Translate the new language files: To translate the language files using RapidAPI, run the following command:

   smart-i18n generate-translations -l fr

   Or use the alias:

   yarn si:trs -l fr

   That's it! Your new language should now be added to the system.

Note: See Automation for more details..

Add New Pages

1. Create a new folder under the app directory, e.g., app/dashboard.
2. Add a new page.tsx file inside the folder.
3. Use the existing components for layout and styles.

---

📚 Tech Stack

Technology	Description
Next.js	React framework with server-side rendering
Next-Auth	Authentication system for Next.js apps
i18next	Localization and translation management
gulp	A toolkit to automate & enhance your workflow
Tailwind CSS	Utility-first CSS framework
shadcn/ui	Beautiful prebuilt components
TypeScript	Static typing for scalable applications
Zod	Type-safe schema validation
@tanstack/react-query	Powerful data fetching library
Vitest	Fast unit testing framework
Playwright	End-to-end browser testing framework
@t3-oss/env-nextjs	Type-safe environment variable management for Next.js
React-Toastify	Toast notifications

---

🚀 Running Tests

This project includes a robust testing setup to ensure code quality and application reliability. Below are the details for running different types of tests:

1. Unit and Integration Tests

We use Vitest with React Testing Library to write and run unit and integration tests.

Run Unit/Integration Tests:

  yarn test

Watch Tests:

  yarn test:watch

Coverage Report:

   yarn coverage

---

2. End-to-End (E2E) Tests

We use Playwright for writing end-to-end tests.

Run E2E Tests:

  yarn test:e2e

Playwright Test Runner UI:

  yarn test:e2e --ui

Notes:

• Ensure the application is running locally before starting E2E tests.
• Configure environment variables in .env.test for test-specific setups.

---

3. Test Setup

• Unit Testing Framework: Vitest
• E2E Testing Framework: Playwright
• Component Testing: React Testing Library

Test Directory Structure

• Unit tests: src/ (next to each component)
• E2E tests: src/tests/e2e/

---

Example Test Command:

  yarn test  # Runs all unit and integration tests
  yarn test:e2e  # Runs all E2E tests

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Author

Made with 💜 by Sayat Raykul

If you like this project, please ⭐️ star it on GitHub! It helps me continue building great open-source tools.

---

📚 Related Projects

• @sayyyat/smart-i18n — The core CLI engine that provides scanning, merging, and type generation.
• @sayyyat/smart-i18n-react — Feature-scaffolding CLI tool that integrates smart-i18n into React/Next.js projects with zero configs.