No native iOS/Android build steps are required. If you use better-sqlite3, ensure your Node.js version matches the pre-built binary; rebuild with npm rebuild better-sqlite3 if you encounter binding errors.

Project setup

1. Copy source. Place the contents of source/ (i.e., the packages/server directory) into your project, for example at vendor/kottster-server/.

2. Configure TypeScript paths. In your root tsconfig.json, add a path alias so imports resolve cleanly:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@kottster/server": ["vendor/kottster-server/lib/index.ts"]
    },
    "module": "CommonJS",
    "target": "ES2020",
    "strict": true
  }
}

3. Set environment variables. The framework reads these at runtime:

APP_SECRET=your-random-secret-32-chars-minimum
NODE_ENV=development          # or production
PORT=5480                     # optional, defaults vary

4. Wire the entry point. Create src/index.ts (see examples below) that calls createApp, createDataSource, and createServer, then starts listening.

5. Build. Use tsc or a bundler like esbuild. The source is plain TypeScript with no special JSX transforms needed.

Public API

createApp

import { createApp } from '@kottster/server';

function createApp(options: { secretKey: string }): App

Instantiates the core App object that holds application-level configuration and state. Pass your APP_SECRET as secretKey. This must be called before creating a server or registering data sources.

createDataSource

import { createDataSource } from '@kottster/server';

function createDataSource(options: {
  type: string;
  adapter: DataSourceAdapter;
}): DataSource

Wraps a Knex adapter into a data source object the app registry can consume. Call once per database connection and register it via the server setup. Use the appropriate Knex*Adapter exported from the same package.

createServer

import { createServer } from '@kottster/server';

function createServer(app: App, options?: ServerOptions): Server

Builds the HTTP server (Express under the hood) with all built-in Kottster routes pre-registered. Returns a Server instance you call .listen() on. Accepts an optional options object for port and middleware configuration.

createIdentityProvider

import { createIdentityProvider } from '@kottster/server';

function createIdentityProvider(input: ExternalIdentityProviderInput): IdentityProvider

Creates an identity provider for authentication. Use this when you want to delegate auth to an external provider rather than the built-in Kottster user store.

ProcedureError

import { ProcedureError } from '@kottster/server';

class ProcedureError extends Error {
  constructor(message: string, code?: string)
}

Throw inside custom procedure handlers to signal a user-facing error. The server catches it and serializes it into a structured error response instead of a 500.

ValidationError

import { ValidationError } from '@kottster/server';

class ValidationError extends Error {
  constructor(message: string, fields?: Record<string, string>)
}

Throw when input validation fails inside a procedure. Carries per-field error metadata that the Kottster UI can display inline on forms.

CachingService

import { CachingService } from '@kottster/server';

class CachingService {
  set(key: string, value: any, ttlSeconds?: number): void
  get<T>(key: string): T | undefined
  invalidate(key: string): void
}

In-process TTL cache. Use it inside custom actions or procedures to avoid redundant database round-trips. Instantiate once and share across handlers.

Working examples

Scenario - Minimal PostgreSQL server

Bootstrap a Kottster admin panel backed by a PostgreSQL database. This is the most common starting point.

import { createApp, createDataSource, createServer, KnexPgAdapter } from '@kottster/server';

const app = createApp({
  secretKey: process.env.APP_SECRET ?? 'change-me-in-production',
});

const pgDataSource = createDataSource({
  type: 'postgres',
  adapter: new KnexPgAdapter({
    client: 'pg',
    connection: {
      host: process.env.DB_HOST ?? 'localhost',
      port: Number(process.env.DB_PORT ?? 5432),
      database: process.env.DB_NAME ?? 'mydb',
      user: process.env.DB_USER ?? 'postgres',
      password: process.env.DB_PASSWORD ?? '',
    },
  }),
});

const server = createServer(app);
server.registerDataSource(pgDataSource);

server.listen(5480, () => {
  console.log('Kottster admin running on http://localhost:5480');
});

Scenario - Throwing typed errors from a custom procedure

Show how to signal validation and procedure failures in a way the Kottster UI understands.

import { ProcedureError, ValidationError, CachingService } from '@kottster/server';

const cache = new CachingService();

async function fetchUserById(id: number) {
  const cached = cache.get<{ name: string }>(`user:${id}`);
  if (cached) return cached;

  if (!id || id <= 0) {
    throw new ValidationError('Invalid input', { id: 'Must be a positive integer' });
  }

  const user = await db('users').where({ id }).first();
  if (!user) {
    throw new ProcedureError(`User with id ${id} not found`, 'USER_NOT_FOUND');
  }

  cache.set(`user:${id}`, user, 60);
  return user;
}

Scenario - SQLite development setup with better-sqlite3

Wire up a local SQLite database for rapid local development without a running database server.

import {
  createApp,
  createDataSource,
  createServer,
  KnexBetterSqlite3Adapter,
} from '@kottster/server';
import path from 'path';

const app = createApp({
  secretKey: process.env.APP_SECRET ?? 'dev-secret-key-do-not-use-in-prod',
});

const sqliteDataSource = createDataSource({
  type: 'sqlite',
  adapter: new KnexBetterSqlite3Adapter({
    client: 'better-sqlite3',
    connection: {
      filename: path.resolve(__dirname, '../data/local.sqlite'),
    },
    useNullAsDefault: true,
  }),
});

const server = createServer(app);
server.registerDataSource(sqliteDataSource);

server.listen(5480);

File walkthrough

• lib/index.ts - Public barrel; the only import surface for consumers.
• lib/version.ts - Exports the current package version string; used by the CLI and API.
• lib/apiReference.ts - Describes the full API surface for introspection by Kottster tooling.
• lib/actions/ - One file per server action (e.g., login, createPage, addDataSource); each action is a discrete async handler invoked by the RPC router.
• lib/adapters/knex/ - Thin wrappers that normalize Knex client configurations for each supported database driver.
• lib/constants/ - Frozen values: HTTP header names, error code strings, resolved project directory paths.
• lib/core/app.ts - App class: holds secret key and app-level state.
• lib/core/server.ts - Server class: Express app factory with Kottster routes mounted.
• lib/core/dataSourceRegistry.ts - Registry that maps named data sources to their adapters at runtime.
• lib/core/identityProvider.ts - Built-in identity provider handling JWT issuance and session validation.
• lib/core/externalIdentityProvider.ts - Delegate interface for OAuth/SSO integration.
• lib/errors/httpError.ts - Generic HTTP error with status code; used internally by the router.
• lib/errors/procedureError.ts - User-facing procedure failure; caught and serialized by the server.
• lib/errors/validationError.ts - Field-level validation failure with metadata map.
• lib/factories/ - Pure factory functions (createApp, createServer, createDataSource, createIdentityProvider) that are the recommended construction path.
• lib/models/ - TypeScript interfaces for action, adapter, error code, and procedure contracts.
• lib/services/caching.service.ts - In-process TTL key/value store.
• lib/services/debugLogger.service.ts - Conditional debug output gated on NODE_ENV.
• lib/services/fileReader.service.ts / fileWriter.service.ts - Read/write project config files from disk.
• lib/services/kottsterApi.service.ts - HTTP client for the Kottster cloud API (schema sync, licensing).
• lib/services/storage.service.ts - Persistent key/value storage backed by the project directory.
• lib/services/exporter.service.ts - Serializes app schema and data for export.
• lib/services/action.service.ts - Dispatches named actions to their handler functions.
• lib/utils/convertName.ts - Converts identifiers between camelCase, snake_case, etc.
• lib/utils/prepareUserForClient.ts - Strips sensitive fields from user objects before sending to the UI.

Common pitfalls and fixes

• APP_SECRET too short or missing. The framework will reject startup or produce weak tokens. Fix: set a random 32+ character string in your environment before running.
• better-sqlite3 native binding mismatch. After Node.js upgrades the prebuilt binary breaks. Fix: run npm rebuild better-sqlite3 inside your project.
• TypeScript path alias not resolving at runtime. tsc strips path aliases; the compiled JS still has them. Fix: use tsconfig-paths (node -r tsconfig-paths/register dist/index.js) or esbuild which resolves aliases at bundle time.
• ESM/CJS interop errors with knex. Some Knex versions ship ESM-only sub-paths. Fix: set "module": "CommonJS" in tsconfig.json and use require-compatible Knex imports.
• Port 5480 already in use on dev machine. The default port collides with another process. Fix: set PORT=<other> and pass it explicitly to server.listen().
• ProcedureError not caught as structured response. Throwing a plain Error instead of ProcedureError causes the server to return a generic 500. Fix: always import and throw ProcedureError or ValidationError from @kottster/server.

Vibe-coding prompt template

I have copied the Kottster Server source into `vendor/kottster-server/` in my project.
I also have USAGE.md in the same directory as this prompt.

Please integrate Kottster Server into my existing Node.js/TypeScript project by:

1. Reading USAGE.md and `vendor/kottster-server/lib/index.ts` to understand the public API.
2. Adding a TypeScript path alias `@kottster/server` → `vendor/kottster-server/lib/index.ts` in my tsconfig.json.
3. Creating `src/admin.ts` that:
   - Calls `createApp` with my APP_SECRET env var.
   - Calls `createDataSource` with the appropriate Knex adapter for my database (ask me which one).
   - Calls `createServer`, registers the data source, and starts listening on PORT env var.
4. Ensuring all imports use the real exported symbols from `lib/index.ts` only.
5. Adding `tsconfig-paths` to dev dependencies and updating my start script if needed.
6. Pointing out any missing peer dependencies for my chosen database driver.

Ask me for my database type and connection details before generating code.
Reference package: @kottster/server (upstream: kottster/kottster, packages/server).

License and credit

Kottster is licensed under the Apache License 2.0. Source and full license text are available at https://github.com/kottster/kottster. The upstream npm package is @kottster/server.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

完整安装指南与集成提示词将在购买后解锁。

CRM, ERP, Admin & Internal Tools

免费