react-router-jam

Key Features

• •Folder-based routing conventions including index (page.tsx), nested (folder+page.tsx), dynamic ([param]), splat ([...param]), layout (layout.tsx), route groups (_folder), and not-found (not-found.tsx). This intuitive naming makes route hierarchy clear at a glance and eliminates complex configuration files.
• •Automatic colocation support: files that do not match naming conventions (page, layout, not-found) are automatically ignored, allowing developers to co-locate components, styles, and tests within route directories without affecting the routing table. This encourages modular code organization.
• •Ignored file patterns configuration via an optional 'ignoredFilePatterns' option using minimatch glob patterns. Developers can exclude specific folders like __tests__ or hooks from route scanning, providing fine-grained control over what gets interpreted as routes.
• •Route groups without URL path: folders prefixed with underscore (_folder) are treated as route groups, enabling logical file organization (e.g., _marketing, _app) without altering the URL structure. A layout.tsx inside a route group can share UI across routes.
• •Route matching priority that follows a clear order: static routes > dynamic segments > splat/catch-all routes. Sibling routes are sorted so specific static paths always take precedence, preventing conflicts and ensuring predictable routing behavior.
• •Direct integration with React Router v7 and Remix: add the 'jamRoutes' function to the app's routes.ts configuration file. It scans the file system and automatically generates typed route configurations with zero manual route definitions.
• •TypeScript (.tsx, .ts) and JavaScript (.jsx, .js) support. The library works with any bundler compatible with React Router, including Bun and Node.js, making it accessible to a wide range of project setups.

Use Cases

• •Building a multi-section dashboard: create nested layouts by adding layout.tsx inside each folder (e.g., admin, settings). Each layout wraps its child pages, sharing common navigation or headers, resulting in a consistent UI structure without code duplication.
• •Creating a blog with dynamic slugs: use a folder named [slug] inside a blog folder. Each post page becomes accessible at /blog/hello-world. This pattern scales easily for thousands of posts and allows co-location of post components and data fetching logic.
• •Organizing marketing pages with route groups: prefix folders with _marketing to group pages like about, contact, and features without adding '/marketing' to URLs. A shared layout inside the route group provides consistent branding across all marketing pages.
• •Handling per-section 404s: place a not-found.tsx file inside a specific directory (e.g., dashboard/not-found.tsx) to show a custom error page for unknown paths under /dashboard. A global not-found.tsx handles the rest, improving user experience and debugging.
• •Co-locating components and test files with routes: by default, files like components/Chart.tsx or __tests__/dashboard.test.tsx are ignored. Developers can additionally use 'ignoredFilePatterns' to exclude subdirectories, keeping the routing clean while allowing feature-based organization.
• •Migrating from flat file routing to folder-based structure: replace flat route files (e.g., about.tsx) with folder+page.tsx patterns. This migration reduces naming conflicts, improves readability, and enables future features like layouts and route groups with minimal effort.

Who is this for?

React developers, front-end engineers, and teams building complex SPAs with React Router v7 or Remix who value organized, scalable routing structures. Ideal for projects requiring clear separation of concerns, nested layouts, and modular codebases. Also suited for developers migrating from flat-file systems to folder-based conventions seeking improved maintainability. The library is designed for those who prefer convention over configuration and want to minimize boilerplate while keeping routes intuitive. Beginners can quickly adopt it due to the straightforward documentation and examples.