How svobik7/next-roots works
Overall Project Type and Purpose
• This is an open‑source CLI tool and library designed to integrate with Next.js (v15+) and generate localized routes.
• Its primary goal is to read original route definitions from a “roots” directory, apply i18n translations (via static/dynamic “i18n.js/ts files”), and produce a new “app” directory containing localized routes.
• It further provides a strongly typed Router class which offers helper methods (such as getHref, getLocaleFromHref, and getRouteFromHref) for linking and route management.
Main Architectural Components
• CLI Interface & Commands:
– The src/cli folder contains commands (like generate and watch) that trigger route generation.
– Commands such as “generateDeclarationFile,” “generateRouterSchemaFile,” etc. are used to compile, translate, and update files.
• Configuration Module:
– The roots.config.js (or roots.config.cjs for ESM) holds configuration parameters (originDir, localizedDir, locales, defaultLocale, prefixDefaultLocale, etc.) that control the generation process.
• Route Generation Engine:
– This module scans the “roots” directory structure, reads translation files (i18n.js/ts, i18n.mjs) alongside route directories, and applies rules to build the “app” folder structure.
– It interacts with file system utilities (found in src/utils and src/cli/utils) to handle file copying, transformation, and deletion (for wiping the “app” folder).
• i18n Translation Module:
– Supports both static and dynamic translation, reading route translation definitions from i18n files placed close to route pages.
– Uses esbuild to compile these translation files, ensuring that both synchronous and async translation modes are supported.
• Router Module/Library:
– Encapsulated in the src/router folder (and tested in router.test.ts) and included as part of the exported API.
– Provides methods for generating URLs based on the generated route schema and is strongly typed using TypeScript.
• File System & Build Integration:
– Contains utilities (e.g., fs-utils, path-utils, rewrite-utils) that manage paths, file operations, and dynamic routing rewrites.
– Integration with build pipelines is supported via GitHub workflows, ESLint, Husky pre-commit hooks, and an example manifest provided in the file tree.
• Testing & Examples:
– A series of examples (e.g., basic, basic-esm, with-preferred-language-catchall, with-preferred-language-middleware) illustrate various usage scenarios.
– End-to-end tests (using Cypress for the “basic” example), Vitest configuration, and mocks in the __mocks__ folder are used to verify functionality.
Relationships & Data Flow Between Components
• The CLI Interface reads the configuration via the configuration module.
• The Route Generation Engine then scans the “roots” folder for route definitions and corresponding translation (i18n) files.
• Using file system utilities, it generates or updates the “app” folder (the output) with localized routes.
• The Router Module leverages a generated schema (from the route generation process) to perform link generation, locale detection, and route mapping at runtime.
• The overall data flow is: Configuration → Route Scanner/Generator (with i18n translation) → File Generation in “app” → Runtime Router for link mapping.
• Integration with Next.js happens through generated route files which include additional props (like locale, pageHref) passed down to pages and layouts.
Architectural Patterns & Design Principles
• Separation of Concerns: The project clearly distinguishes between static configuration, dynamic route generation, CLI operations, and runtime routing.
• Modular Design: Each folder (CLI, src/utils, src/router, src/cli/templates) represents a separate module/functionality.
• Extensibility: The tooling supports both static and dynamic translations and allows custom post-generation actions via afterGenerate callbacks.
• Strong Typing: The use of TypeScript and detailed type definitions enhances reliability (for example, in the Router class methods).
• Build Integration: Use of esbuild for compiling i18n files and integration with GitHub workflows for CI/CD underscores modern build practices.
Elements
– “CLI Interface (src/cli)”
– “Configuration Module (roots.config.js)”
– “Route Scanner & Generator Engine”
– “i18n Translation Handler”
– “File System Utilities”
– “Router Module (src/router)”
– “Generated App Folder (Output)”
– From the “Configuration Module” into the “Route Generator.”
– From the “Route Generator” into file creation, updating the “app” folder.
– From the “Router Module” referencing the generated route schema and then feeding pages.
– Another for core processing (route generation, i18n translation).
– A third for runtime components (Router, Next.js integration).
• Optionally, include integration points (ESLint, Husky, GitHub workflows) as side modules that affect quality and deployment.