@nikovirtala/projen-constructs

Projen project types with standard configuration for consistent project setup across all repositories.

Installation

pnpm add -D @nikovirtala/projen-constructs projen constructs

Features

• Standard Configuration: Opinionated defaults for author, release branch, package manager, Node.js, TypeScript, and tooling
• Automatic Project Type Discovery: Generates ProjectType enum from Projen's JSII manifest (18 project types)
• Component System: Reusable components (Vitest, Mise, TypeDoc, LocalStack, etc.)
• Code Generation: ProjectGenerator creates project classes with standard configuration
• ES Modules: TypeScript and CDK App projects use ES modules (JSII uses CommonJS)
• Code Quality: Biome for formatting and linting
• Testing: Vitest with coverage
• Auto-merge: Enabled with auto-approve
• VSCode: Recommended extensions and settings
• mise: Node version management

Standard Configuration

• Author: Niko Virtala ([email protected])
• Default Release Branch: main
• Package Manager: pnpm 10
• Node Version: 22.21.1
• TypeScript: 5.9.3
• CDK Version: 2.223.0 (for CDK projects)
• JSII Version: ~5.9.3 (for JSII projects)

Customization

Override any option by passing it to the constructor:

const project = new JsiiProject({
  name: "my-project",
  repositoryUrl: "https://github.com/nikovirtala/my-project.git",
  minNodeVersion: "20.0.0",
  author: "Custom Author",
  authorAddress: "[email protected]",
  mise: false,
  vitest: false,
  tsconfig: {
    compilerOptions: {
      noUnusedLocals: false,
    },
  },
  biomeOptions: {
    biomeConfig: {
      formatter: {
        lineWidth: 100,
      },
    },
  },
});

Usage

Projects

AWS CDK Construct Library Project

import { AwsCdkConstructLibraryProject } from "@nikovirtala/projen-constructs";

const project = new AwsCdkConstructLibraryProject({
  name: "my-cdk-construct",
  repositoryUrl: "https://github.com/nikovirtala/my-cdk-construct.git",
});

project.synth();

AWS CDK TypeScript App Project

import { AwsCdkTypeScriptAppProject } from "@nikovirtala/projen-constructs";

const project = new AwsCdkTypeScriptAppProject({
  name: "my-cdk-app",
  repositoryUrl: "https://github.com/nikovirtala/my-cdk-app.git",
});

project.synth();

JSII Project

import { JsiiProject } from "@nikovirtala/projen-constructs";

const project = new JsiiProject({
  name: "my-jsii-project",
  repositoryUrl: "https://github.com/nikovirtala/my-jsii-project.git",
});

project.synth();

TypeScript Project

import { TypeScriptProject } from "@nikovirtala/projen-constructs";

const project = new TypeScriptProject({
  name: "my-typescript-project",
  repositoryUrl: "https://github.com/nikovirtala/my-typescript-project.git",
});

project.synth();

Components

The package includes reusable components for common development tasks:

Vitest

Vitest testing framework component.

import { Vitest } from "@nikovirtala/projen-constructs";

new Vitest(project, {
  vitestVersion: "^4",
  config: {
    coverageProvider: CoverageProvider.V8,
    coverageReporters: [CoverageReporter.TEXT, CoverageReporter.LCOV],
  },
});

TypeDoc

TypeDoc documentation generation component.

import { TypeDoc, EntryPointStrategy } from "@nikovirtala/projen-constructs";

new TypeDoc(project, {
  version: "^0.28",
  typeDocConfig: {
    entryPointStrategy: EntryPointStrategy.EXPAND,
    out: "docs/api",
    exclude: ["**/*.test.ts"],
  },
});

Mise

Mise dev tools/runtimes management component.

import { Mise } from "@nikovirtala/projen-constructs";

new Mise(project, {
  nodeVersion: "22.21.1",
});

Homebrew

Homebrew package management component.

import { Homebrew } from "@nikovirtala/projen-constructs";

const homebrew = new Homebrew(project, {
  packages: ["jq", "yq"],
});

homebrew.addPackage("gh");

Colima

Colima container runtime component. Alternative for Docker.

import { Colima } from "@nikovirtala/projen-constructs";

new Colima(project);

LocalStack

LocalStack AWS emulation component.

import { LocalStack } from "@nikovirtala/projen-constructs";

new LocalStack(project, {
  services: ["s3", "lambda", "dynamodb"],
  port: 4566,
  debug: true,
});

LambdaFunctionConstructGenerator

Generates AWS CDK Lambda Function constructs and bundles their code.

import { LambdaFunctionConstructGenerator } from "@nikovirtala/projen-constructs";

new LambdaFunctionConstructGenerator(project, {
  sourceDir: "src/handlers",
  outputDir: "src/constructs/lambda",
  filePattern: "*.lambda.ts",
  esbuildOptions: {
    minify: true,
    sourcemap: true,
  },
});

Bundler

Low-level bundling utilities for Lambda functions.

import {
  Bundler,
  LambdaFunctionCodeBundle,
} from "@nikovirtala/projen-constructs";

const bundler = new Bundler(project, {
  assetsDir: "assets",
  esbuildVersion: "^0.25",
});

new LambdaFunctionCodeBundle(project, {
  entrypoint: "src/my-function.lambda.ts",
  extension: ".lambda.ts",
});

ProjectGenerator

Generates TypeScript project classes with standard configuration.

import { ProjectGenerator, ProjectType } from "@nikovirtala/projen-constructs";

new ProjectGenerator(project, {
  name: "TypeScriptProject",
  projectType: ProjectType.TYPESCRIPT,
  filePath: "./src/projects/typescript.generated.ts",
  components: [
    { componentClass: Mise },
    { componentClass: Vitest }, // Auto-detects VitestOptions from JSII manifest
  ],
});

Features:

• Automatically generates the ProjectType enum from Projen's JSII manifest
• Auto-detects component options types from JSII manifests
• Validates paths to prevent directory traversal attacks
• Structured error handling with custom error classes