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.

Hướng dẫn cài đặt đầy đủ và prompt tích hợp sẽ mở khóa sau khi mua.

Medusa Open Source Commerce Platform Backend

eCommerce, Marketplace & POS Systems

Miễn phí