Routing da filesystem

Entrambi gli stack costruiscono le rotte a partire dal filesystem. La regola è la stessa in ciascuno: la posizione di un file è il suo percorso URL. Non registri mai le rotte a mano.

Le regole

Efesto analizza la tua directory delle rotte e ricava un percorso per ogni file:

1. Le cartelle sono segmenti di percorso. routes/users/... vive sotto /users.
2. index mappa la sua cartella. routes/users/index.ts → /users.
3. [param] diventa un parametro di rotta. routes/users/[id].ts → /users/:id.
4. L'estensione viene rimossa e quale estensione viene analizzata dipende da isProduction: .ts in sviluppo, .js in produzione.

routes/
├── index.ts            # /            (root)
├── health.ts           # /health
├── users/
│   ├── index.ts        # /users
│   ├── [id].ts         # /users/:id
│   └── [id]/
│       └── posts.ts    # /users/:id/posts
└── products/
    └── index.ts        # /products

Un prefisso di mount viene anteposto a tutti questi. Con un prefisso /api/v1, routes/users/[id].ts serve /api/v1/users/:id.

Modifica qui sotto il percorso del file o il prefisso per vedere l'endpoint che Efesto ricava:

Mount prefix

Route file

→/api/v1/users/:id

Impostare la directory delle rotte e il prefisso

Express

La directory delle rotte è options.absoluteDirRoutes (accetta un array per analizzarne diverse). Il prefisso di mount deriva da dove monti il middleware Express:

app.use(
  "/api/v1", // <- prefisso
  efesto({
    authMiddleware,
    errorMiddleware,
    isProduction: process.env.NODE_ENV === "production",
    options: {
      absoluteDirRoutes: path.join(__dirname, "routes"), // <- dir delle rotte
    },
  })
);

Leggi i parametri di rotta da req.params (es. req.params.id per [id].ts). Il loro tipo documentato è controllato da dynamicParameterType ("string" di default).

Bun/Elysia

La directory delle rotte è routesDir (accetta anch'essa un array). Il prefisso è prefix:

const app = efesto({
  isProduction: process.env.NODE_ENV === "production",
  routesDir: `${import.meta.dir}/routes`, // <- dir delle rotte
  prefix: "/api/v1",                       // <- prefisso
});

Un file [id].ts diventa il segmento Elysia :id; leggilo dal contesto params tipizzato. Ogni modulo di rotta usa internamente percorsi relativi ("/"), Efesto monta il modulo al prefisso ricavato per te.

Cosa deve esportare un file

Express

Un export default di una classe che estende BaseApiService. Un file che non ne esporta una non è una rotta valida. Vedi Creare endpoint.

Bun/Elysia

Un export default di una istanza Elysia nativa oppure di una classe/istanza che estende BaseApiService. Qualsiasi altra cosa viene saltata con un avviso nella console. Vedi Bun/Elysia.

Sviluppo vs produzione

Il flag isProduction seleziona l'estensione del file che Efesto analizza:

• isProduction: false → analizza .ts (esecuzione da sorgente con ts-node / bun).
• isProduction: true → analizza i .js compilati (esecuzione dal tuo output di build).

Mantieni l'output di build speculare all'albero dei sorgenti così che i percorsi ricavati restino identici tra sviluppo e produzione.

Una volta che un file è al suo posto, definisci la rotta.