Quickstart

Prerequisites

• Node.js >= 20
• pnpm >= 9 (recommended) or npm
• AWS credentials configured (for deployment)

1. Install the CLI

npm install -g @venturekit/cli@dev

2. Create a New Project

vk init my-app

The CLI will prompt you for a template:

• Minimal — Basic API with a health check endpoint
• API — REST API with authentication and scoped endpoints
• Fullstack — API + database + storage

Or skip prompts with flags:

vk init my-app --template api --yes

3. Install Dependencies

cd my-app
npm install

4. Explore the Project

Your project has this structure:

my-app/
├── config/
│   ├── base.ts        # Project identity (name, region)
│   ├── security.ts    # OAuth scopes and app clients
│   ├── dev.ts         # Dev environment (nano preset)
│   ├── stage.ts       # Staging environment
│   └── prod.ts        # Production environment
├── src/
│   └── routes/
│       └── health/
│           └── get.ts # GET /health
├── vk.config.ts
├── package.json
└── tsconfig.json

vk.config.ts

This is the entry point. It wires everything together:

import { defineVenture } from '@venturekit/infra';
import { base } from './config/base';
import { security } from './config/security';
import { dev } from './config/dev';
import { stage } from './config/stage';
import { prod } from './config/prod';

export default defineVenture({
  base,
  security,
  envs: { dev, stage, prod },
  routesDir: 'src/routes',
});

src/routes/health/get.ts

A public endpoint — no scopes means no authentication required:

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

export const main = handler(async (_body, ctx, logger) => {
  logger.info('Health check requested');
  return {
    status: 'healthy',
    timestamp: ctx.timestamp.toISOString(),
    requestId: ctx.requestId,
  };
});

5. Start Development

vk dev

This starts a local development server with Docker services for your infrastructure. Handlers are loaded at runtime — edit a file and the next request uses the new code.

Test your endpoint:

curl http://localhost:3000/health

6. Add a Route

Generate a new authenticated endpoint:

vk g route tasks -m post --scopes tasks.write

This creates src/routes/tasks/post.ts:

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

export const main = handler(
  async (body, ctx, logger) => {
    logger.info('POST /tasks', { requestId: ctx.requestId });
    return { message: 'Hello from POST /tasks' };
  },
  { scopes: ['tasks.write'] }
);

Note

Remember to add the tasks.write scope to your config/security.ts and assign it to an app client.

7. Deploy

# Deploy to dev
vk deploy

# Deploy to production
vk deploy --stage prod

Next Steps

• Configuration — Understand the layered config system.
  • File-Based Routing — Learn the routing conventions.
  • Handlers — Deep dive into the unified handler.
  • Infrastructure Intents — Declare databases, storage, queues, and more.