He
HeliumTS
Note:

HeliumTS is under active development. Expect bugs and breaking changes. If you find any issues, please report them in our GitHub

A stable release is planned for early 2026.

Routing

Overview

HeliumTS uses file-based routing similar to Next.js Pages Router. Pages are automatically mapped to routes based on their file path in the src/pages directory. The framework provides a powerful routing system with support for dynamic routes, catch-all routes, layouts, and route groups.

In this section:

File-Based Routing

Basic Routes

Files in src/pages are automatically mapped to routes:

1src/pages/
2├── index.tsx           → /
3├── about.tsx           → /about
4├── contact.tsx         → /contact
5└── blog/
6    ├── index.tsx       → /blog
7    └── post.tsx        → /blog/post

Dynamic Routes

Use square brackets [param] to create dynamic routes:

1src/pages/
2├── users/
3│   └── [id].tsx        → /users/:id (matches /users/123, /users/abc, etc.)
4├── blog/
5│   └── [slug].tsx      → /blog/:slug
6└── products/
7    └── [category]/
8        └── [id].tsx    → /products/:category/:id

Example usage:

1// src/pages/users/[id].tsx
2import { useRouter } from "heliumts/client";
3

4export default function UserPage() {
5    const router = useRouter();
6    const userId = router.params.id;  // Get the dynamic parameter
7    
8    return <div>User ID: {userId}</div>;
9}

Catch-All Routes

Use [...param] to match any number of path segments:

1src/pages/
2└── docs/
3    └── [...slug].tsx   → /docs/* (matches /docs/a, /docs/a/b/c, etc.)

Example usage:

1// src/pages/docs/[...slug].tsx
2import { useRouter } from "heliumts/client";
3

4export default function DocsPage() {
5    const router = useRouter();
6    const slug = router.params.slug;  // Array of path segments
7    
8    return <div>Docs path: {Array.isArray(slug) ? slug.join('/') : slug}</div>;
9}

Index Routes

Files named index.tsx represent the root of their directory:

1src/pages/
2├── index.tsx           → /
3├── blog/
4│   ├── index.tsx       → /blog
5│   └── post.tsx        → /blog/post
6└── admin/
7    └── index.tsx       → /admin

Route Groups

Route groups allow you to organize pages without affecting URLs. Wrap folder names in parentheses:

1src/pages/
2├── (marketing)/
3│   ├── _layout.tsx     # Layout for marketing pages
4│   ├── index.tsx       → /
5│   ├── about.tsx       → /about
6│   └── pricing.tsx     → /pricing
7├── (app)/
8│   ├── _layout.tsx     # Layout for app pages
9│   ├── dashboard.tsx   → /dashboard
10│   └── settings.tsx    → /settings
11└── (auth)/
12    ├── _layout.tsx     # Layout for auth pages
13    ├── login.tsx       → /login
14    └── register.tsx    → /register

The route group folders (marketing), (app), and (auth) are stripped from URLs but allow you to:

  • Organize related pages
  • Apply different layouts per group
  • Keep code organized by feature/domain

Layouts

Layouts allow you to share UI between pages. Create _layout.tsx files to wrap pages with shared headers, sidebars, and footers.

See Layouts for detailed documentation on root layouts, group layouts, and nested layouts.

SSR-Aware Routing

Routing, layouts, and route groups also work with server-rendered pages. If a page opts into "use ssr";, HeliumTS renders the layout tree on the server before sending HTML to the browser.

See SSR for request-time rendering details and Route Groups for layout scoping.

Route Collision Detection

Helium automatically detects when multiple files resolve to the same URL:

1❌ Route collision detected! Multiple files resolve to the same path "/":
2   - /src/pages/index.tsx
3   - /src/pages/(marketing)/index.tsx
4Only the first file will be used.

Common causes:

  • Multiple index.tsx files at the same level
  • Same filename in different route groups
  • Mixed grouped and non-grouped files

Solution: Use unique filenames or nest pages in subdirectories.