Skip to content
VentureKit

Quickstart

Prerequisites

Section titled “Prerequisites”
  • Node.js >= 20
  • pnpm >= 9 (recommended) or npm
  • AWS credentials configured (for deployment)

1. Install the CLI

Section titled “1. Install the CLI”
Terminal window
npm install -g @venturekit/cli@dev

2. Create a New Project

Section titled “2. Create a New Project”
Terminal window
vk init my-app

You’ll be prompted to choose a template:

TemplateDescription
API (default)REST API with auth and scoped endpoints
API + DatabaseAPI with Postgres database and migrations
API + QueueAPI with SQS queue consumer
API + StorageAPI with S3 storage and file uploads
FullstackAPI + Database + Storage + Queue

Dependencies are installed automatically. Or skip prompts with defaults:

Terminal window
vk init my-app --yes

3. Explore the Project

Section titled “3. 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 (preset + overrides)
│   └── prod.ts            # Production environment (preset + overrides)
├── src/
│   └── routes/
│       ├── health/
│       │   └── get.ts     # GET /health
│       └── tasks/
│           ├── get.ts     # GET /tasks (authenticated)
│           └── post.ts    # POST /tasks (authenticated)
├── vk.config.ts               # Entry point — base, security, infra definitions, envs
├── package.json
└── tsconfig.json

vk.config.ts

Section titled “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 { prod } from './config/prod';


export default defineVenture({
  base,
  security,
  envs: { dev, prod },
});

src/routes/health/get.ts

Section titled “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,
  };
});

4. Start Development

Section titled “4. Start Development”
Terminal window
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:

Terminal window
curl http://localhost:3000/health

5. Add a Route

Section titled “5. Add a Route”

Generate a new route with a dynamic segment:

Terminal window
vk g route "tasks/[id]" -m put --scopes tasks.write

This creates src/routes/tasks/[id]/put.ts:

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


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

6. Deploy

Section titled “6. Deploy”
Terminal window
# Deploy to dev
vk deploy


# Deploy to production
vk deploy --stage prod

Next Steps

Section titled “Next Steps”