File-Based Routing

VentureKit automatically discovers API routes from your file system. No manual route registration is needed.

Convention

Routes live in your routesDir (typically src/routes/). Each file maps to an API endpoint based on its directory path and filename:

src/routes/<path>/<method>.ts  →  <METHOD> /<path>

Examples

File	Route
src/routes/health/get.ts	GET /health
src/routes/tasks/get.ts	GET /tasks
src/routes/tasks/post.ts	POST /tasks
src/routes/tasks/[id]/get.ts	GET /tasks/{id}
src/routes/tasks/[id]/put.ts	PUT /tasks/{id}
src/routes/tasks/[id]/delete.ts	DELETE /tasks/{id}
src/routes/admin/users/get.ts	GET /admin/users

Supported HTTP Methods

The filename determines the HTTP method:

Filename	Method
get.ts	GET
post.ts	POST
put.ts	PUT
patch.ts	PATCH
delete.ts	DELETE

Dynamic Segments

Use square brackets for path parameters:

src/routes/tasks/[id]/get.ts       →  GET /tasks/{id}
src/routes/users/[userId]/posts/[postId]/get.ts  →  GET /users/{userId}/posts/{postId}

Dynamic segments are converted to API Gateway path parameters ({id}, {userId}, etc.) and are available in ctx.rawEvent.pathParameters.

Handler Format

Every route file must export a main function created with handler():

src/routes/tasks/get.ts

import { handler } from '@venturekit/runtime';

export const main = handler(async (_body, ctx, logger) => {
  logger.info('Listing tasks');
  return [{ id: '1', title: 'Learn VentureKit' }];
});

Generating Routes

Use the CLI to generate route files:

# Generate GET /tasks
vk g route tasks

# Generate POST /tasks with scopes
vk g route tasks -m post --scopes tasks.write

# Generate DELETE /tasks/{id}
vk g route tasks/[id] -m delete --scopes tasks.write

Configuration

Set the routes directory in your vk.config.ts:

export default defineVenture({
  // ...
  routesDir: 'src/routes',
});

The path is relative to your project root.