Overview

Bini.js uses a folder-based routing system where the folder structure inside src/app/ directly maps to URL paths. This makes routing intuitive and eliminates the need for manual route configuration.

Basic Folder Routing

Each folder inside src/app/ becomes a URL segment. Add a page.tsx file inside to make the route publicly accessible.

This creates four routes: /, /about, /blog, and /contact.

Flat File Support

Bini.js also supports flat files at the root level. These work the same way as folder-based routes:

Nested Routes

Nest folders inside each other to create nested URL segments. Each level adds another segment to the URL path.

The folder structure directly mirrors the URL structure. Deep nesting is fully supported up to 100 levels deep.

Dynamic Segments

Use square brackets [param] to create dynamic route segments that match any value. Access the value with useParams() (auto-imported).

Dynamic Folder Example

Using Dynamic Params

// src/app/blog/[slug]/page.tsx
export default function BlogPost() {
  const { slug } = useParams() // Auto-imported
  
  return (
    <article>
      <h1 className="text-3xl font-bold text-white">Post: {slug}</h1>
    </article>
  )
}

Flat File Dynamic Routes

Catch-all Segments

Use [...segment] to match multiple URL segments. The parameter becomes an array of values.

Catch-all Example

// src/app/docs/[...slug]/page.tsx
export default function DocsPage() {
  const { slug } = useParams()
  // slug is an array: ['api', 'reference']
  
  return (
    <div>
      <h1 className="text-2xl font-bold text-white">Documentation</h1>
      <p className="text-slate-400">Path: {slug?.join(' / ')}</p>
    </div>
  )
}

Flat File Catch-all

Optional Catch-all Segments

Use [[...segment]] to make the catch-all optional. The route will also match the parent path.

Optional Catch-all Example

// src/app/shop/[[...slug]]/page.tsx
export default function ShopPage() {
  const { slug } = useParams()
  // slug is undefined for /shop
  // slug is ['clothing'] for /shop/clothing
  
  if (!slug) {
    return <h1 className="text-2xl font-bold text-white">Shop Home</h1>
  }
  
  return (
    <div>
      <h1 className="text-2xl font-bold text-white">
        Category: {slug.join(' / ')}
      </h1>
    </div>
  )
}

Route Groups

Use parentheses (group) to organize routes without affecting the URL. Perfect for grouping related pages or applying shared layouts.

Route Group Example

Notice how (marketing), (shop), and (admin) don't appear in the URLs. They're purely for organization.

Route Groups with Layouts

Route groups are especially useful for applying different layouts to different sections:

Private Folders

Prefix a folder with an underscore _folder to exclude it from routing. Perfect for components, utilities, and other non-route files.

Private Folder Example

Private folders can be placed anywhere in the app directory and are completely ignored by the router.

Ignored Patterns

• Folders starting with _ (underscore)
• Folders starting with . (dot)
• Files starting with _ or .
• The api/ directory (reserved for API routes)

Nearest Wins with Folders

loading.tsx, not-found.tsx, and error.tsx follow the folder hierarchy using "nearest wins" resolution. A file in a subfolder only affects that subfolder and shadows (without deleting) the same file in any ancestor folder.

Folder Hierarchy and Boundaries

• Each folder can define its own loading.tsx, error.tsx, and not-found.tsx
• A file in a subfolder only affects routes inside that subfolder
• It shadows the same file in ancestor folders for routes in that subfolder
• Routes without a closer match fall through to the nearest ancestor
• If no file exists anywhere in the hierarchy, the built-in default is used

Example Structure

Resolution Flow

When a route needs a boundary file, the router checks:

1. The route's own folder first
2. Each parent folder (going up the hierarchy)
3. The built-in default if no file is found

Route Priority

When multiple routes could match a URL, Bini.js resolves them in this order:

Priority Example

Consider this folder structure:

This ensures predictable routing behavior and prevents conflicts between different route types.

Complete Example

Here is a comprehensive folder structure showing all routing patterns:

Route Mapping