Skip to content
ContractSpec
Start here
AI index

Import Existing Codebases

Convert your existing API endpoints into ContractSpec contracts. Auto-detect frameworks, extract schemas, and generate explicit contract definitions from your code.

What you'll learn

  • How to import existing API endpoints as ContractSpec contracts.

  • Framework-specific patterns and auto-detection.

  • Customizing imports with scopes, dry-run, and output options.

  • Registering imported contracts and adding handlers.

Why import existing code?

Instead of writing contracts from scratch, the import command extracts endpoint patterns from your existing codebase. This gives you:

  • Instant spec coverage for existing APIs

  • Type-safe schemas derived from your existing types

  • A foundation to iterate and refine contracts

  • Gradual adoption without rewriting code

Supported frameworks

NestJS

Controllers, decorators, DTOs

--framework nestjs

Express

Router methods, middleware

--framework express

Fastify

Route definitions, schemas

--framework fastify

Hono

Route handlers, validators

--framework hono

Elysia

Type-safe routes, schemas

--framework elysia

tRPC

Procedure definitions

--framework trpc

Next.js

API routes (app/api, pages/api)

--framework next-api

1) Quick start

Run the import command to auto-detect your framework and extract endpoints:

bash
# Auto-detect framework and import all endpoints
contractspec import ./src

# Preview what would be imported (dry-run)
contractspec import ./src --dry-run

# Force a specific framework
contractspec import ./src --framework nestjs

Expected output: A summary of endpoints found, schemas extracted, and files generated.

2) Framework-specific patterns

The import command recognizes these patterns in each framework:

NestJS

typescript
@Controller('users')
export class UsersController {
  @Get(':id')
  async getUser(@Param('id') id: string): Promise<UserDto> {
    return this.usersService.findOne(id);
  }

  @Post()
  @UseGuards(AuthGuard)
  async createUser(@Body() dto: CreateUserDto): Promise<UserDto> {
    return this.usersService.create(dto);
  }
}

Detected: @Controller, @Get, @Post, @Body, @Param, @UseGuards decorators.

Express

typescript
const router = express.Router();

router.get('/users/:id', async (req, res) => {
  const user = await getUserById(req.params.id);
  res.json(user);
});

router.post('/users', validateBody(CreateUserSchema), async (req, res) => {
  const user = await createUser(req.body);
  res.status(201).json(user);
});

Detected: router.get, router.post, validation middleware, Zod schemas.

Next.js API Routes

typescript
export async function GET(
  request: Request,
  { params }: { params: { id: string } }
) {
  const user = await getUserById(params.id);
  return Response.json(user);
}

export async function POST(request: Request) {
  const body = await request.json();
  const user = await createUser(body);
  return Response.json(user, { status: 201 });
}

Detected: GET, POST exports in app/api/**/route.ts and pages/api/**/*.ts.

3) Understanding generated contracts

The import command generates ContractSpec operations with IMPLEMENTATION_REQUIRED placeholders for fields it cannot infer:

typescript
import { defineQuery, defineCommand } from "@lssm-tech/lib.contracts-spec";
import { SchemaModel, ScalarTypeEnum } from "@lssm-tech/lib.schema";

export const GetUserQuery = defineQuery({
  meta: {
    key: "users.get",
    version: "1.0.0",
    description: "IMPLEMENTATION_REQUIRED: Add description",
    stability: "draft",
    owners: ["IMPLEMENTATION_REQUIRED"],
    tags: ["users"],
  },
  io: {
    input: new SchemaModel({
      name: "GetUserInput",
      fields: {
        id: { type: ScalarTypeEnum.String(), isOptional: false },
      },
    }),
    output: new SchemaModel({
      name: "GetUserOutput",
      fields: {
        // IMPLEMENTATION_REQUIRED: Add output fields based on your UserDto
        id: { type: ScalarTypeEnum.String(), isOptional: false },
      },
    }),
  },
  policy: { auth: "user" }, // Inferred from @UseGuards
  transport: {
    rest: { method: "GET", path: "/users/:id" },
  },
});

export const CreateUserCommand = defineCommand({
  meta: {
    key: "users.create",
    version: "1.0.0",
    description: "IMPLEMENTATION_REQUIRED: Add description",
    stability: "draft",
    owners: ["IMPLEMENTATION_REQUIRED"],
    tags: ["users"],
  },
  io: {
    input: new SchemaModel({
      name: "CreateUserInput",
      fields: {
        // IMPLEMENTATION_REQUIRED: Add fields from CreateUserDto
      },
    }),
    output: new SchemaModel({
      name: "CreateUserOutput",
      fields: {
        id: { type: ScalarTypeEnum.String(), isOptional: false },
      },
    }),
  },
  policy: { auth: "admin" },
  transport: {
    rest: { method: "POST", path: "/users" },
  },
});

4) Customizing imports

Available options

Option

Description

Example

--scope

Limit to specific directories

--scope src/users src/auth
--framework

Force a specific framework

--framework express
--output

Output directory

--output ./contracts
--dry-run

Preview without writing files

--dry-run
--analyze

Analysis only, no code generation

--analyze
--json

Output as JSON for scripting

--json
bash
# Import only specific modules
contractspec import ./src --scope src/users src/orders

# Preview with analysis
contractspec import ./src --dry-run --analyze

# Output to custom directory
contractspec import ./src --output ./src/contracts/generated

# Get JSON for CI/scripting
contractspec import ./src --json > import-result.json

5) Registering imported contracts

After import, register contracts and add handlers:

typescript
import {
  OperationSpecRegistry,
  installOp,
} from "@lssm-tech/lib.contracts-spec/operations";
import {
  GetUserQuery,
  CreateUserCommand,
} from "./.contractspec/generated/users.operation";

export const registry = new OperationSpecRegistry();

// Add handlers to imported operations
installOp(registry, GetUserQuery, async (input) => {
  const user = await db.user.findUnique({ where: { id: input.id } });
  return user;
});

installOp(registry, CreateUserCommand, async (input) => {
  const user = await db.user.create({ data: input });
  return { id: user.id };
});

6) After importing

  1. Review generated contracts — Check the IMPLEMENTATION_REQUIRED placeholders and fill in descriptions, owners, and tags.

  2. Refine schemas — Add proper types, validation rules, and error definitions.

  3. Run validation —contractspec validate to ensure contracts are valid.

  4. Register and wire handlers — Connect contracts to your existing business logic.

  5. Iterate — The imported contracts are a starting point. Refine them as your spec matures.

Troubleshooting

Framework not detected

Use --framework <name> to force a specific framework. Check that your entry files follow standard patterns.

Missing schemas

Schema inference works best with explicit types. If using any or dynamic types, you'll see IMPLEMENTATION_REQUIRED placeholders. Fill them in manually.

Partial imports

Some endpoints may not be detected if they use unconventional patterns. Use --analyze to see what was found, then add missing contracts manually.

Want evidence-driven migration priorities?

Studio clusters product signals into scored patterns, then proposes contract changes and execution-ready work for the highest-impact areas.

See what Studio adds