BCP Framework

BCP Framework is a React full-stack application framework for file-based routing, SSR, server data, APIs, authentication, SQL databases, jobs, workflows, transactional events, realtime, caching, observability, plugins, dependency injection, deployment lifecycle and standalone Node.js production builds.

Development target: 0.3.1 — Dependency Injection & Service Container

0.3.1 remains unreleased until local validation, RC checks, tagging and npm publication complete.

Current platform

| Area | Capability | | --- | --- | | Application runtime | defineApp() / createApp(), typed config, DI, plugins/modules, resource lifecycle, readiness and diagnostics | | Dependency injection | Typed tokens, value/factory/class providers, singleton/scoped/transient lifetimes, child scopes and test overrides | | Routing | Static, dynamic, catch-all, optional catch-all and route groups | | Rendering | React SSR, hydration, layouts, metadata and SPA navigation | | Server data | Route loaders, guards, actions and request-scoped server APIs | | Authentication | JWT cookie sessions, revocation, logout-all and idle timeout | | Authorization | Auth/guest/role/permission guards and resource-aware policies | | Database | MySQL, PostgreSQL and SQLite adapters, transactions, lifecycle and migrations | | Jobs | Delay, retries, scheduling, Redis-compatible durable queues, heartbeat, recovery and DLQ | | Workflows | Sequential/parallel steps, retries, persisted delays, compensation and run leases | | Events | Transactional outbox, SQL persistence, dispatcher leases and durable handoff | | Realtime | Channels, presence, broker delivery, WebSocket adapter contract, SSE and heartbeat | | Plugins | Dependency ordering, lifecycle, config parsing, legacy shared services and async hooks | | Cache | Redis-compatible adapters/locks, stampede protection, TTL/tag/path invalidation and metrics | | Observability | Prometheus metrics, health/readiness, distributed tracing, W3C context and correlation IDs | | Deployment | Resource lifecycle, readiness, diagnostics, runtime identity and graceful shutdown | | Testing | Request/route/page/auth/database/middleware/jobs/workflow/outbox/realtime/SSE harnesses | | Stability | API baseline snapshot, package-export parity and release-readiness gates | | Production | Standalone Node.js build, compiled server runtimes, dependency pruning and Docker starter |

Requirements

• Node.js 24.11.0 or newer
• React 19
• npm

Optional SQL drivers:

MySQL       mysql2
PostgreSQL  pg
SQLite      better-sqlite3

Quick start

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

Generated projects normally use one framework dependency:

{
  "dependencies": {
    "bcp": "npm:@chidchanun/bcp@latest"
  }
}

Dependency Injection & Service Container — 0.3.1

0.3.1 adds the server-only bcp/container entrypoint.

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

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

const clientToken =
    createServiceToken<{
        apiUrl: string;
    }>("api-client");

const container =
    createServiceContainer({
        providers: [
            provideValue(
                configToken,
                {
                    apiUrl: "https://api.example.com",
                }
            ),
            provideFactory(
                clientToken,
                [
                    configToken,
                ] as const,
                (_context, [config]) => ({
                    apiUrl: config.apiUrl,
                })
            ),
        ],
    });

const client =
    await container.resolve(
        clientToken
    );

Supported lifetimes:

singleton  one shared instance
scoped     one instance per child/request scope
transient  a new instance for every resolve

Testing/request overrides use child scopes:

const testScope =
    container.createScope({
        name: "test",
        overrides: [
            provideValue(
                configToken,
                fakeConfig
            ),
        ],
    });

Resolved disposable services are cleaned up in reverse creation order. Circular dependency graphs fail with ServiceResolutionError instead of returning partial objects.

Read more: Dependency Injection & Service Container.

BCP Application Platform — 0.3.x

bcp/application is the server-side composition root.

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

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

export const app =
    createApp({
        name: "orders-api",
        version: "1.0.0",
        providers: [
            provideValue(
                configToken,
                {
                    region: "ap-southeast-1",
                }
            ),
        ],
        async setup(context) {
            const config =
                await context.container.resolve(
                    configToken
                );
        },
    });

The application exposes:

app.config
app.container
app.services
app.hooks
app.plugins
app.deployment

app.services remains the Plugin Platform compatibility registry. New typed dependencies should prefer app.container.

Applications can register DI providers before start:

app.register(provider);

and create request/job/test scopes:

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

Infrastructure resources still use app.addResource().

Application startup order:

application.setup()
        ↓
bcp:container
        ↓
plugin setup/start
        ↓
resources start
        ↓
application.start()
        ↓
ready

Shutdown reverses resource dependencies, so injected services remain alive until application resources/plugins have stopped. The container is then disposed, followed by application.dispose().

Read more: Application Platform and Migrating to 0.3.x.

Public entrypoints — 0.3.1 baseline

bcp
bcp/island
bcp/cache
bcp/config
bcp/validation
bcp/error
bcp/database
bcp/auth
bcp/jobs
bcp/workflow
bcp/events
bcp/realtime
bcp/testing
bcp/plugins
bcp/observability
bcp/deployment
bcp/container
bcp/application
bcp/server
bcp/server-only
bcp/middleware

Application code should use public entrypoints rather than private packages/* files.

Core backend composition

import { createApp } from "bcp/application";
import { createServiceContainer } from "bcp/container";
import { createCacheStore } from "bcp/cache";
import { db } from "bcp/database";
import { createAuth } from "bcp/auth";
import { createJobQueue } from "bcp/jobs";
import { createWorkflow } from "bcp/workflow";
import { createTransactionalOutbox } from "bcp/events";
import { createRealtime } from "bcp/realtime";
import { createPluginHost } from "bcp/plugins";
import { createTracer } from "bcp/observability";
import { createDeploymentRuntime } from "bcp/deployment";

These systems remain independently usable. Application Platform coordinates selected instances and the DI container adds typed dependency composition.

Compiled production entrypoints

Prepared npm packages use compiled ESM for the main server runtime surfaces:

bcp/cache          -> cache.mjs
bcp/config         -> config.mjs
bcp/database       -> database.mjs
bcp/auth           -> auth.mjs
bcp/jobs           -> jobs.mjs
bcp/workflow       -> workflow.mjs
bcp/events         -> events.mjs
bcp/realtime       -> realtime.mjs
bcp/testing        -> testing.mjs
bcp/plugins        -> plugins.mjs
bcp/observability  -> observability.mjs
bcp/deployment     -> deployment.mjs
bcp/container      -> container.mjs
bcp/application    -> application.mjs
bcp/server         -> server.mjs
bcp/middleware     -> middleware.mjs

The reviewed prepared export map is recorded in docs/api-freeze-snapshot.json and validated by npm run api:check.

CLI

bcp dev
bcp build
bcp package
bcp start
bcp routes
bcp update
bcp config check
bcp doctor
bcp inspect
bcp version

Database migrations:

bcp db create create_users
bcp db migrate
bcp db status
bcp db rollback

Generators:

bcp generate page dashboard/users
bcp generate api users
bcp generate middleware
bcp generate migration create_users

API baseline and release readiness

0.2.19 froze the 0.2.x contract. 0.3.0 established the Application Platform baseline. 0.3.1 advances that baseline additively with bcp/container and no intentional breaking changes from 0.3.0.

npm run api:check
npm run release:readiness
npm run release:readiness:report

Regenerate the snapshot only for an intentional reviewed baseline change:

npm run api:snapshot

Machine-readable contracts

docs/platform-manifest.json
docs/docs-web-manifest.json
docs/api-manifest.json
docs/api-freeze-snapshot.json

Release validation

Before publishing 0.3.1:

npm run typecheck
npm run test:unit
npm run test:integration
npm run test:e2e
npm run test:package
npm run api:check
npm run release:readiness
npm run rc:check

Do not tag or publish until the exact final release commit passes the full RC sequence.

Release history

| Version | Milestone | | --- | --- | | 0.1.24 | File Upload Foundation | | 0.1.25 | Storage Adapters and File Delivery | | 0.1.26 | S3-Compatible Storage and Production Streaming | | 0.1.27 | Storage Ecosystem | | 0.1.28 | Production Hardening | | 0.1.29 | Developer Experience | | 0.2.0 | Framework Platform | | 0.2.1 | Documentation Platform | | 0.2.2 | Configuration & Environment v2 | | 0.2.3 | Database Platform v2 | | 0.2.4 | Application Packaging | | 0.2.5 | Authentication Platform v2 | | 0.2.6 | Authorization & Security v2 | | 0.2.7 | Observability Platform v2 | | 0.2.8 | Background Jobs Platform | | 0.2.9 | Job Scheduling Platform | | 0.2.10 | Durable Jobs Platform | | 0.2.11 | Workflow Orchestration | | 0.2.12 | Transactional Outbox & Events | | 0.2.13 | Realtime Platform | | 0.2.14 | Testing Platform | | 0.2.15 | Plugin & Module Platform | | 0.2.16 | Cache Platform v2 | | 0.2.17 | Observability Platform v3 | | 0.2.18 | Deployment Platform v2 | | 0.2.19 | Stability & API Freeze | | 0.3.0 | BCP Application Platform | | 0.3.1 | Dependency Injection & Service Container |

Roadmap

The next milestone is 0.3.2 — Module System v2, focused on application-native modules that can compose providers, plugins, routes, middleware, jobs and lifecycle contributions around the createApp() composition root.

Later 0.3.x milestones expand routing/API contracts, repositories, validation/DTOs, SDK generation, identity/authorization, multi-tenancy, developer tooling and build/runtime targets.

Native desktop/mobile compilation remains later roadmap work.

License

BCP Framework and create-bcp-app are released under the MIT License.