He
HeliumTS
Note:

HeliumTS is under pre-beta and 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 December 2025.

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.

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.