vector

Blazing fast, secure, and developer-friendly API framework for Bun.

Vector is a Bun-first framework for building HTTP APIs with declarative route files, strong TypeScript inference, and zero runtime dependencies.

• Zero Dependencies: No runtime routing dependency
• Bun Native: TypeScript-first workflow with the Bun runtime
• Type Safe: Typed request/auth/context with schema-driven validation
• Built In: Middleware, auth hooks, caching, CORS, OpenAPI generation

Installation

bun add vector-framework

Requirements:

• Bun >= 1.0.0

Quick Start

1. Create vector.config.ts

import type { VectorConfigSchema } from "vector-framework";

const config: VectorConfigSchema = {
  // number | string: TCP port for Bun.serve (string is coerced with Number() at runtime)
  port: process.env.PORT ?? 3000,
  // string: host/interface to bind
  hostname: "localhost",
  // boolean: enables dev-oriented defaults (OpenAPI JSON on by default)
  development: process.env.NODE_ENV !== "production",
  // string: route discovery directory
  routesDir: "./routes",
  // number (seconds): keep-alive timeout for idle connections
  idleTimeout: 60,
  defaults: {
    route: {
      // boolean: expose route publicly by default
      expose: true,
      // boolean | AuthKind: auth requirement default for routes
      auth: false,
      // boolean: enable schema.input validation by default
      validate: true,
      // boolean: return handler value as-is when true
      rawResponse: false,
    },
  },
};

export default config;

2. Create a route file

// routes/hello.ts
import { route } from "vector-framework";

export const hello = route(
  { method: "GET", path: "/hello", expose: true },
  async (ctx) => {
    return { message: "Hello world" };
  },
);

3. Run the server

bun vector dev

Your API will be available at http://localhost:3000.

Production Start

bun vector start --config ./vector.config.ts --routes ./routes --port 8080 --host 0.0.0.0

Notes:

• start uses the same config and route options as dev.
• start sets NODE_ENV=production.
• File watching is only enabled for dev.

Programmatic Start

import { startVector } from "vector-framework";

const app = await startVector({
  configPath: "./vector.config.ts",
});

console.log(`Listening on ${app.server.hostname}:${app.server.port}`);

Notes:

• startVector() does not enable file watching.
• app.stop() stops immediately (used for dev reload flows).
• await app.shutdown() performs graceful shutdown and runs config shutdown hook.

Optional: Validation + OpenAPI

bun add -d zod

Vector is not tied to Zod. It supports any validation library that implements the StandardSchemaV1 interface (~standard v1).

Common compatible choices include:

• Zod (v4+)
• Valibot
• ArkType

For OpenAPI schema conversion, your library also needs StandardJSONSchemaV1 (~standard.jsonSchema.input/output). If those converters are missing, runtime validation still works, but schema conversion is skipped.

import { route } from "vector-framework";
import { z } from "zod";

const CreateUserInput = z.object({
  body: z.object({
    email: z.string().email(),
    name: z.string().min(1),
  }),
});

const CreateUserSchema = { input: CreateUserInput };

export const createUser = route(
  { method: "POST", path: "/users", expose: true, schema: CreateUserSchema },
  async (ctx) => {
    return { created: true, email: ctx.validatedInput.body.email };
  },
);

Enable OpenAPI in vector.config.ts:

openapi: {
  enabled: true,
  path: '/openapi.json',
  docs: false,
}

Documentation

Start here for deeper guides:

• Docs Index
• Configuration
• Routing and Request API
• TypeScript Types
• Schema Validation
• OpenAPI and Docs UI
• CLI and Route Discovery
• Error Reference
• Migration Notes
• Performance Notes

Examples

• examples/routes/health.ts
• examples/routes/events.ts
• examples/routes/commerce.ts
• tests/e2e/test-routes.ts (broader endpoint patterns)
• tests/e2e/test-zod-routes.ts (Zod + I/O validation flows)

Contributing

Contributions are welcome. Open an issue or pull request.

License

MIT