create-bcp-app

Create a new BCP Framework project.

npx create-bcp-app my-app
cd my-app
npm run dev

Project-local BCP CLI

Generated npm scripts use the local framework CLI:

{
  "scripts": {
    "dev": "bcp dev",
    "build": "bcp build",
    "package": "bcp package",
    "start": "bcp start",
    "routes": "bcp routes",
    "generate": "bcp generate",
    "update": "bcp update"
  }
}

For direct PowerShell usage, prefer the collision-free alias:

npm exec -- bcp-framework --version
npm exec -- bcp-framework doctor
npm exec -- bcp-framework inspect
npm exec -- bcp-framework routes
npm exec -- bcp-framework dev
npm exec -- bcp-framework build
npm exec -- bcp-framework package

Microsoft SQL Server can install another Windows executable named bcp.exe, so bcp-framework is the recommended interactive Windows command name.

Interactive choices

Use Tailwind CSS?
Select a database:
  None
  MySQL
  PostgreSQL
  SQLite
  MongoDB
Select authentication:
  None
  JWT Cookie
Select storage provider:
  None
  Local Server
  Amazon S3
  Cloudflare R2

Generated project metadata

New projects include bcp.project.json.

Example for the 0.3.1 target:

{
  "schemaVersion": 1,
  "framework": "bcp",
  "projectName": "my-app",
  "frameworkPackage": "npm:@chidchanun/[email protected]",
  "createdWith": {
    "package": "create-bcp-app",
    "version": "0.3.1"
  },
  "packageManager": "npm",
  "presets": {
    "tailwind": true,
    "database": "mysql",
    "auth": "jwt-cookie",
    "storage": "local"
  }
}

This manifest records scaffold identity only. Do not place secrets in it.

Application Platform

Applications can centralize server infrastructure through bcp/application:

import {
    createApp,
} from "bcp/application";

export const app =
    createApp({
        name: "my-app",
    });

Existing BCP subsystem APIs remain independently usable.

Dependency Injection & Service Container — 0.3.1+

Typed dependencies use bcp/container:

import {
    createServiceToken,
    provideFactory,
    provideValue,
} from "bcp/container";

const configToken =
    createServiceToken<{
        apiUrl: string;
    }>("config");

const repositoryToken =
    createServiceToken<UserRepository>(
        "user-repository"
    );

export const app =
    createApp({
        name: "my-app",
        providers: [
            provideValue(
                configToken,
                {
                    apiUrl: "https://api.example.com",
                }
            ),
            provideFactory(
                repositoryToken,
                [
                    configToken,
                ] as const,
                (_context, [config]) =>
                    createRepository(
                        config.apiUrl
                    )
            ),
        ],
    });

Resolve from server/application code:

const repository =
    await app.container.resolve(
        repositoryToken
    );

Supported lifetimes:

singleton
scoped
transient

For request/job/test boundaries:

const scope =
    app.createScope({
        name: "request:123",
    });

Testing overrides:

const testScope =
    app.createScope({
        name: "test",
        overrides: [
            provideValue(
                mailerToken,
                fakeMailer
            ),
        ],
    });

DI is optional. Existing app.services and plugin service registries remain supported.

Lifecycle resources

Long-running infrastructure still uses Deployment Platform resources:

app.addResource({
    name: "database",

    start() {
        return database.connect();
    },

    ready() {
        return database.ready;
    },

    stop() {
        return database.close();
    },
});

In 0.3.1, the DI container remains active until application resources and plugins have stopped, then disposes injected services in reverse creation order.

Database presets

• MySQL: mysql2
• PostgreSQL: pg
• SQLite: better-sqlite3
• MongoDB: mongodb
• None: no database dependency

For MySQL, PostgreSQL and SQLite, generated lib/database.ts exposes BCP database primitives through bcp/database.

Authentication and security

The JWT Cookie preset creates starter authentication code. BCP supports revocable session stores, permission/policy authorization, route guards and same-origin/CSRF helpers.

Jobs, workflows, events and realtime

Use bcp/jobs, bcp/workflow, bcp/events and bcp/realtime directly or register selected instances with the Application Platform/DI container.

Testing

bcp/testing provides framework-native request/route/page/auth/database/middleware/jobs/workflow/outbox/realtime helpers. DI scope overrides complement these helpers for application-level dependency replacement.

Plugins

bcp/plugins remains available for reusable plugin/module lifecycle composition. Plugin definitions/modules can be passed to createApp().

Observability and deployment

bcp/observability provides metrics/tracing. bcp/deployment remains available when an application wants to own resource lifecycle directly; bcp/application reuses its readiness/diagnostics/shutdown model.

Application packaging

npm run build
npm run package

BCP 0.3.1 prepared packages include compiled container.mjs and application.mjs server runtimes. Project .env files and application devDependencies are excluded from deployment packages.

Project generators

npm run generate -- page dashboard/users
npm run generate -- api users
npm run generate -- middleware
npm run generate -- migration create_users

Options

--no-install              Create files without running npm install
--tailwind                Enable Tailwind CSS without prompting
--no-tailwind             Disable Tailwind CSS without prompting
--database <database>     none | mysql | postgresql | sqlite | mongodb
--auth <preset>           none | jwt-cookie
--storage <provider>      none | local | amazon-s3 | cloudflare-r2
-y, --yes                 Accept defaults
--bcp <specifier>         Override dependencies.bcp
-h, --help                Show help

For prerelease/local package verification:

npx create-bcp-app my-app --bcp file:../chidchanun-bcp-0.3.1.tgz