No native iOS/Android linking is required. sharp performs a native binary download at install time; ensure your CI/CD platform matches your deployment OS architecture (e.g., linux/amd64 for Docker).

Project setup

1. Copy source: Place the contents of source/ into a packages/ directory at your project root, mirroring the monorepo layout, or install individual packages from npm if only consuming (not modifying) them.

2. TypeScript config - Add path aliases if building from source:

{
  "compilerOptions": {
    "paths": {
      "@vendure/core": ["packages/core/src/index.ts"],
      "@vendure/common/lib/*": ["packages/common/src/*"],
      "@vendure/admin-ui-plugin": ["packages/admin-ui-plugin/index.ts"],
      "@vendure/asset-server-plugin": ["packages/asset-server-plugin/index.ts"]
    },
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

3. Entry point - packages/core/src/index.ts is the main export surface. Import bootstrap and VendureConfig from there.

4. Environment variables - Required at minimum:

APP_ENV=production          # enables prod mode in admin-ui
DB_HOST=localhost
DB_PORT=5432
DB_NAME=vendure
DB_USERNAME=vendure
DB_PASSWORD=secret
SUPERADMIN_USERNAME=superadmin
SUPERADMIN_PASSWORD=yourpassword

5. Bootstrap - Create a src/index.ts:

import 'reflect-metadata';
import { bootstrap } from '@vendure/core';
import { config } from './vendure-config';

bootstrap(config).catch(err => {
    console.error(err);
    process.exit(1);
});

6. Migrations - Run with:

npx ts-node -e "require('@vendure/core').runMigrations(config)"

Public API

bootstrap

function bootstrap(userConfig: VendureConfig): Promise<INestApplication>

The primary entry point. Accepts a VendureConfig object and returns a running NestJS application. Call this once in your server entry file. It handles database connection, plugin initialization, GraphQL schema generation, and HTTP server startup.

loadAppConfig

function loadAppConfig(): Promise<void>

Used in the Admin UI (admin-ui/src/main.ts) to fetch the runtime app configuration from the server before Angular bootstraps. Call this before platformBrowserDynamic().bootstrapModule(AppModule) to ensure API endpoint and auth configuration is available to the Angular DI system.

runMigrations

function runMigrations(config: VendureConfig): Promise<void>

Exported from core/src/migrate. Executes pending TypeORM migrations against the configured database. Use this in CI/CD pipelines or startup scripts before launching the server to keep the schema in sync with entity changes.

Permission (enum)

enum Permission {
    Authenticated,
    SuperAdmin,
    Owner,
    Public,
    // ...channel and resource-specific permissions
}

Re-exported from @vendure/common/lib/generated-types. Use with the @Allow() decorator on GraphQL resolvers to declare which permissions are required to access a field or mutation.

Working examples

Scenario - Minimal server bootstrap

A bare-minimum Vendure server with SQLite, the default admin UI, and the asset server plugin.

import 'reflect-metadata';
import { VendureConfig, bootstrap } from '@vendure/core';
import { AdminUiPlugin } from '@vendure/admin-ui-plugin';
import { AssetServerPlugin } from '@vendure/asset-server-plugin';
import * as path from 'path';

const config: VendureConfig = {
    apiOptions: {
        port: 3000,
        adminApiPath: 'admin-api',
        shopApiPath: 'shop-api',
    },
    authOptions: {
        superadminCredentials: {
            identifier: process.env.SUPERADMIN_USERNAME ?? 'superadmin',
            password: process.env.SUPERADMIN_PASSWORD ?? 'superadmin',
        },
    },
    dbConnectionOptions: {
        type: 'better-sqlite3',
        synchronize: false,
        migrations: [path.join(__dirname, '../migrations/*.js')],
        database: path.join(__dirname, '../vendure.sqlite'),
    },
    plugins: [
        AssetServerPlugin.init({
            route: 'assets',
            assetUploadDir: path.join(__dirname, '../static/assets'),
        }),
        AdminUiPlugin.init({
            route: 'admin',
            port: 3002,
        }),
    ],
};

bootstrap(config).catch(console.error);

Scenario - Custom GraphQL resolver with permission guard

Adding a custom admin API resolver that requires the SuperAdmin permission.

import { Resolver, Query } from '@nestjs/graphql';
import { Allow, Permission, RequestContext, Ctx } from '@vendure/core';

@Resolver()
export class ReportResolver {
    @Query()
    @Allow(Permission.SuperAdmin)
    async salesReport(@Ctx() ctx: RequestContext): Promise<string> {
        // ctx carries the active channel, session, and language
        return `Report for channel: ${ctx.channel.code}`;
    }
}

Register ReportResolver inside a Vendure plugin's adminApiExtensions to wire it into the schema automatically.

Scenario - S3 asset storage

Swapping local disk storage for S3 using the built-in S3AssetStorageStrategy.

import { AssetServerPlugin } from '@vendure/asset-server-plugin';
import { configureS3AssetStorage } from '@vendure/asset-server-plugin';
import * as path from 'path';

AssetServerPlugin.init({
    route: 'assets',
    assetUploadDir: path.join(__dirname, '../static/assets'),
    storageStrategyFactory: configureS3AssetStorage({
        bucket: process.env.S3_BUCKET ?? 'my-vendure-assets',
        credentials: {
            accessKeyId: process.env.AWS_ACCESS_KEY_ID ?? '',
            secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY ?? '',
        },
        nativeS3Configuration: {
            region: process.env.AWS_REGION ?? 'us-east-1',
        },
    }),
});

File walkthrough

• core/ - Houses every server-side concern: bootstrap.ts, all NestJS services, TypeORM entities, GraphQL resolvers, the plugin API, event bus, job queue abstraction, and i18n. This is the central package.
• admin-ui/ - Angular 17+ workspace. src/lib/ contains feature modules (catalog, orders, customers, settings). src/app/ is the shell. Built output is consumed by admin-ui-plugin.
• admin-ui-plugin/ - Thin NestJS plugin (index.ts → src/plugin.ts) that serves the compiled admin UI static files and wires up the app config endpoint.
• asset-server-plugin/ - Exposes AssetServerPlugin, S3AssetStorageStrategy, SharpAssetPreviewStrategy, and HashedAssetNamingStrategy. All configurable via init().
• common/ - Shared generated GraphQL types (generated-types.ts) and hand-written shared-types.ts. Never import from common directly in application code; re-exported through core.
• email-plugin/ - Template-based email sending. Supports SMTP, Sendgrid, and custom transports. Register email handlers per lifecycle event.
• job-queue-plugin/ - Drop-in persistent job queue. Configure BullMQ (Redis) or database-backed strategy.
• harden-plugin/ - Adds rate-limiting, disables introspection in production, and sets strict CORS. Use in all production deployments.
• testing/ - TestServer and helper factories for integration tests. Avoids needing a real database in CI with in-memory SQLite support.
• cli/ - Scaffolds new plugins, generates migrations, and adds UI extensions via interactive prompts.
• create/ - create-vendure-app npm initializer. Not imported at runtime.
• ui-devkit/ - Compiles Angular extensions into the admin UI bundle. Used when building custom UI plugins.
• telemetry-plugin/ - Optional anonymous telemetry. Safe to omit.
• graphiql-plugin/ - Mounts a GraphiQL IDE at a configurable route. Dev use only.
• dev-server/ - Local development bootstrap with watch mode. Not for production.
• dashboard/ - Experimental next-gen React dashboard. Not production-ready.

Common pitfalls and fixes

• emitDecoratorMetadata not enabled: NestJS dependency injection silently fails. Fix: add "emitDecoratorMetadata": true and "experimentalDecorators": true to every tsconfig.json in the build chain.
• reflect-metadata not imported first: Decorator metadata is unavailable at runtime. Fix: import 'reflect-metadata' must be the very first line in your server entry file, before any other imports.
• Sharp binary mismatch in Docker: sharp ships platform-specific binaries. Fix: run npm rebuild sharp inside the Docker build step after copying node_modules, or install inside the container rather than copying from a host Mac.
• synchronize: true in production: TypeORM will auto-alter tables and can cause data loss. Fix: always set synchronize: false and use runMigrations() in production.
• Admin UI plugin port conflict: AdminUiPlugin spawns a dev server on a separate port during development. Fix: set the port option explicitly and ensure it does not collide with your API port.
• Missing APP_ENV / prod mode not enabled: The Angular admin UI logs errors to the console that are suppressed in prod mode. Fix: ensure environment.production = true maps to enableProdMode() by setting the correct Angular build configuration (--configuration production).

Vibe-coding prompt template

I have the Vendure Core monorepo source in `source/` and this integration guide in `USAGE.md`.
The upstream package is `user@example.com` (packages: `@vendure/core`, `@vendure/admin-ui-plugin`,
`@vendure/asset-server-plugin`, etc.).

My project is a Node.js / TypeScript backend. Please help me integrate Vendure step-by-step:

1. Read `USAGE.md` and the file excerpts in `source/core/src/index.ts` to understand all exports.
2. Create `src/vendure-config.ts` with a `VendureConfig` using my existing database settings.
3. Create `src/index.ts` that calls `bootstrap(config)` from `@vendure/core`.
4. Add `AssetServerPlugin` and `AdminUiPlugin` to the plugins array.
5. Generate an initial migration using `@vendure/core`'s `generateMigration`.
6. Add a custom resolver that uses `@Allow`, `@Ctx`, `RequestContext`, and `Permission` from `@vendure/core`.
7. Show me the `tsconfig.json` changes needed for `emitDecoratorMetadata` and path aliases.
8. Explain any environment variables I need to set.

Do not invent any APIs. Only use exports visible in `source/core/src/index.ts`,
`source/admin-ui-plugin/index.ts`, and `source/asset-server-plugin/index.ts`.

License and credit

Vendure Core is licensed under the GPLv3 license (see source/LICENSE.md or the repository LICENSE). Commercial licensing for enterprise use is available via the Vendure pricing page. Upstream source: github.com/vendurehq/vendure.

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

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

Medusa Open Source Commerce Platform Backend

eCommerce, Marketplace & POS Systems

免费