🇺🇸English

SPA Routes and Features Guide

SPA structure:

• src/spa/ – Entry points (entry.web.tsx, entry.mobile.tsx, entry.desktop.tsx) and router config (router/). Router lives here to avoid confusion with src/routes/.
• src/routes/ – Page segments only (roots).
• src/features/ – Business logic and UI by domain.

This project uses a roots vs features split: src/routes/ only holds page segments; business logic and UI live in src/features/ by domain.

Agent constraint — desktop router parity: Edits to the desktop route tree must update both src/spa/router/desktopRouter.config.tsx and src/spa/router/desktopRouter.config.desktop.tsx in the same change (same paths, nesting, index routes, and segment registration). Updating only one causes drift; the missing tree can fail to register routes and surface as a blank screen or broken navigation on the affected build.

When to Use This Skill

• Adding a new SPA route or route segment
• Defining or refactoring layout/page files under src/routes/
• Moving route-specific components or logic into src/features/
• Deciding where to put a new component (route folder vs feature folder)

1. What Belongs in src/routes/ (roots)

Each route directory should contain only :

Rule: Route files should only import and compose. No new features/ folders or heavy components inside src/routes/.

2. What Belongs in src/features/

Put domain-oriented UI and logic here:

• Layout building blocks: sidebars, headers, body panels, drawers
• Hooks and store usage for that domain
• Domain-specific forms, lists, modals, etc.

Organize by domain (e.g. Pages, Home, Agent, PageEditor), not by route path. One route can use several features; one feature can be used by several routes.

Each feature should:

• Live under src/features/<FeatureName>/
• Export a clear public API via index.ts or index.tsx
• Use @/features/<FeatureName>/... for internal imports when needed

3. How to Add a New SPA Route

1. Choose the route group

   • (main)/ – desktop main app
   • (mobile)/ – mobile
   • (desktop)/ – Electron-specific
   • onboarding/, share/ – special flows

2. Create only segment files undersrc/routes/

   • e.g. src/routes/(main)/my-feature/_layout/index.tsx and src/routes/(main)/my-feature/index.tsx (and optional [id]/index.tsx).

3a. Desktop router pair (desktopRouter.config × 2)

Anything that changes the tree (new segment, renamed path, moved layout, new child route) must be reflected in both files in one PR or commit. Remove routes from both when deleting.

4. How to Divide Files (route vs feature)

Examples

• Route (thin):
  src/routes/(main)/page/_layout/index.tsx → export { default } from '@/features/Pages/PageLayout'
• Feature (real implementation):
  src/features/Pages/PageLayout/ → Sidebar, DataSync, Body, Header, styles, etc.
• Route (thin):
  src/routes/(main)/page/index.tsx → Import PageTitle, PageExplorerPlaceholder from @/features/Pages and @/features/PageExplorer; render with <PageTitle /> and placeholder.

5. Progressive Migration (existing code)

We are migrating existing routes to this structure step by step:

• Phase 1 (done): /page route – segment files in src/routes/(main)/page/, implementation in src/features/Pages/.
• Later phases: home, settings, agent/group, community/resource/memory, mobile/share/onboarding.

When touching an old route that still has logic or features/ inside src/routes/:

1. Prefer adding new code in src/features/<Domain>/ and importing from routes.
2. For larger refactors, move existing route-only logic into the right feature and then thin out the route files (re-export or compose from features).
3. Use git mv when moving files so history is preserved.

6. Reference Structure (after Phase 1)

Route (thin):

src/routes/(main)/page/
├── _layout/index.tsx   → re-export or compose from @/features/Pages/PageLayout
├── index.tsx          → import from @/features/Pages, @/features/PageExplorer
└── [id]/index.tsx     → import from @/features/Pages, @/features/PageExplorer

Feature (implementation):

src/features/Pages/
├── index.ts            → export PageLayout, PageTitle
├── PageTitle.tsx
└── PageLayout/
    ├── index.tsx       → Sidebar + Outlet + DataSync
    ├── DataSync.tsx
    ├── Sidebar.tsx
    ├── style.ts
    ├── Body/           → list, actions, drawer, etc.
    └── Header/         → breadcrumb, add button, etc.

Router config continues to point at route paths (e.g. @/routes/(main)/page, @/routes/(main)/page/_layout); route files then delegate to features.

Weekly Installs

84

Repository

lobehub/lobehub

GitHub Stars

74.6K

First Seen

Mar 1, 2026

Security Audits

Gen Agent Trust HubPassSocketPassSnykPass

Installed on

codex82

cursor82

kimi-cli81

gemini-cli81

amp81

cline81