Exploring Vendure: A Comprehensive Guide to the Open-Source Headless Commerce Platform

Abdul Aziz Ahwan
25 Jun, 2024

In the realm of e-commerce, choosing the right platform is pivotal for the success of an online store. Vendure, an open-source headless commerce platform, has emerged as a robust solution built on modern technologies like Node.js, GraphQL, Nest, and TypeScript. With a strong focus on developer productivity and ease of customization, Vendure offers a flexible and scalable solution for businesses of all sizes. In this comprehensive guide, we'll explore the features, setup process, development guidelines, and best practices for using Vendure to build your next e-commerce project.

Introduction to Vendure

Vendure is a modern headless commerce platform designed to be highly customizable and developer-friendly. It leverages the power of Node.js for server-side execution, GraphQL for efficient data querying, NestJS for structured and scalable application architecture, and TypeScript for robust and type-safe code. This combination of technologies ensures that Vendure not only performs well but is also easy to extend and customize to meet specific business needs.

Key Features of Vendure:

  • Headless Architecture: Vendure separates the backend from the frontend, allowing developers to build custom frontends using any technology.
  • GraphQL API: Provides a flexible and powerful API for querying and mutating data.
  • Plugin System: Easily extend the functionality of Vendure with custom plugins.
  • TypeScript: Ensures type safety and reduces runtime errors.
  • NestJS Framework: Offers a modular architecture that makes it easy to manage complex applications.
  • Developer-Friendly: Focuses on making the development process smooth and efficient.

Getting Started with Vendure

Getting Vendure up and running locally is straightforward. This section will guide you through the initial setup process, including installation, server configuration, and running the development server.

Installation

To start with Vendure, you need to have Node.js and npm (or Yarn) installed on your machine. Once these prerequisites are met, you can install Vendure using npm:

npm install -g @vendure/cli

After installing the CLI, you can create a new Vendure project with the following command:

vendure new my-vendure-project
cd my-vendure-project
npm install

Setting Up the Server

Vendure requires an SQL database to operate. It officially supports MySQL, PostgreSQL, and SQLite. For development purposes, using SQLite is the simplest option. However, if you prefer to use MySQL or PostgreSQL, you can set up the database using Docker.

Configuring the Database

Vendure uses TypeORM for database interactions. You need to configure the database connection settings in the vendure-config.ts file located in the root of your project.

Here's an example configuration for SQLite:

import { VendureConfig } from '@vendure/core';

export const config: VendureConfig = {
  // Other configuration settings
  dbConnectionOptions: {
    type: 'sqlite',
    synchronize: true,
    logging: false,
    database: 'vendure.sqlite',
  },
  // Other configuration settings
};

For MySQL or PostgreSQL, you need to update the dbConnectionOptions accordingly:

import { VendureConfig } from '@vendure/core';

export const config: VendureConfig = {
  // Other configuration settings
  dbConnectionOptions: {
    type: 'mysql', // or 'postgres'
    host: 'localhost',
    port: 3306, // or 5432 for PostgreSQL
    username: 'your-username',
    password: 'your-password',
    database: 'vendure',
    synchronize: true,
    logging: false,
  },
  // Other configuration settings
};

Populating Mock Data

Vendure provides a convenient script to populate your database with mock data for testing and development purposes:

npm run populate --DB=sqlite

If you are using MySQL or PostgreSQL, replace sqlite with the appropriate database type.

Running the Development Server

Once the database is configured and populated with data, you can start the Vendure server:

npm run start

This command starts the server and makes it accessible at http://localhost:3000. You can access the admin interface at http://localhost:3000/admin, and the GraphQL API is available at http://localhost:3000/shop-api.

Vendure Architecture

Vendure is designed as a monorepo, which means that all the packages required for the platform are contained within a single repository. This structure simplifies dependency management and ensures that all parts of the system are compatible.

Monorepo Structure

The Vendure monorepo is managed with Lerna, a tool that optimizes the workflow around managing multi-package repositories. Here's an overview of the directory structure:

vendure/
├── docs/           # Documentation source
├── e2e-common/     # Shared config for package e2e tests
├── packages/       # Source for the Vendure server, admin-ui & plugin packages
├── scripts/
    ├── changelog/  # Scripts used to generate the changelog based on the git history
    ├── codegen/    # Scripts used to generate TypeScript code from the GraphQL APIs
    ├── docs/       # Scripts used to generate documentation markdown from the source

Packages Overview

Vendure's core functionality is divided into several packages, each responsible for different aspects of the platform. Here are some of the key packages:

  • @vendure/core: The core package containing the main application logic, GraphQL APIs, and database interactions.
  • @vendure/admin-ui: The admin interface built with Angular, providing a user-friendly interface for managing the e-commerce platform.
  • @vendure/create: A package for scaffolding new Vendure projects.
  • @vendure/testing: Utilities and setup for running tests in Vendure.

Each package is located in the packages/ directory and follows a consistent structure, making it easy to navigate and understand the codebase.

Development Workflow

Developing with Vendure involves building the project, making changes to the codebase, testing those changes, and ensuring everything works as expected. This section outlines the essential steps in the development workflow.

Building the Project

Before making any changes, you need to build the project to compile TypeScript code, build the admin UI, and prepare other assets. Run the following command from the root directory:

npm run build

This command builds all the packages and may take a few minutes to complete.

Testing Changes Locally

To test changes locally, you need to set up a development server and possibly make changes to specific packages. Here is how you can test changes to the payments-plugin package:

  1. Open two terminal windows:
    • Terminal 1: For watching and compiling changes in the payments-plugin package.
    • Terminal 2: For running the development server.
# Terminal 1
cd packages/payments-plugin
npm run watch

If you are developing changes for the core package, you also need to watch the common package:

#

 Terminal 1
# Root of the project
npm run watch:core-common
  1. Start the development server after the changes are compiled:
# Terminal 2
cd packages/dev-server
DB=sqlite npm run start

The development server will now include your local changes from the modified package.

Code Generation

Vendure uses graphql-code-generator to automatically generate TypeScript interfaces for all GraphQL server operations and admin UI queries. This ensures type safety and reduces the likelihood of errors when interacting with the GraphQL API.

Run the following command to generate the necessary types:

npm run codegen

This command generates several files, including:

  • packages/common/src/generated-types.ts: Types, inputs, and resolver arguments for the Admin API.
  • packages/common/src/generated-shop-types.ts: Types, inputs, and resolver arguments for the Shop API.
  • packages/admin-ui/src/lib/core/src/common/generated-types.ts: Types and operations for admin UI queries and mutations.
  • packages/admin-ui/src/lib/core/src/common/introspection-result.ts: Used by the Apollo Client IntrospectionFragmentMatcher to correctly handle fragments in the Admin UI.

Customizing Vendure

One of Vendure's main strengths is its flexibility and ease of customization. This section explores how to extend the core functionality and create custom plugins to tailor Vendure to your specific needs.

Extending the Core

Vendure's modular architecture allows developers to extend core functionality without modifying the source code. You can create new services, extend existing ones, and add custom resolvers to the GraphQL API.

Here's an example of how to add a custom service:

import { Injectable } from '@nestjs/common';
import { RequestContext, TransactionalConnection } from '@vendure/core';

@Injectable()
export class CustomService {
  constructor(private connection: TransactionalConnection) {}

  async customMethod(ctx: RequestContext, someParam: string) {
    // Custom logic here
  }
}

To use this custom service, you need to register it in your Vendure configuration:

import { CustomService } from './path-to-custom-service';

export const config: VendureConfig = {
  // Other configuration settings
  providers: [
    CustomService,
    // Other providers
  ],
  // Other configuration settings
};

Creating Plugins

Plugins are a powerful way to add new features or integrate third-party services with Vendure. A plugin can define new GraphQL resolvers, extend existing services, add custom entities, and more.

Here's an example of a simple plugin:

import { VendurePlugin, PluginCommonModule } from '@vendure/core';
import { AdminUiExtension } from '@vendure/ui-devkit';
import path from 'path';

@VendurePlugin({
  imports: [PluginCommonModule],
  providers: [],
  adminUi: {
    path: path.join(__dirname, 'admin-ui'),
    ngModules: [
      {
        type: 'shared',
        ngModuleFileName: 'custom-ui-extension.module.ts',
        ngModuleName: 'CustomUiExtensionModule',
      },
    ],
  },
})
export class CustomPlugin {}

To use this plugin, add it to your Vendure configuration:

import { CustomPlugin } from './path-to-custom-plugin';

export const config: VendureConfig = {
  // Other configuration settings
  plugins: [
    CustomPlugin,
    // Other plugins
  ],
  // Other configuration settings
};

Testing in Vendure

Testing is a crucial part of the development process, ensuring that your code works as expected and does not introduce regressions. Vendure provides comprehensive support for both unit tests and end-to-end (e2e) tests.

Unit Tests

Unit tests are co-located with the files they test and have the suffix .spec.ts. You can run all unit tests with the following command:

npm run test

To run tests for a specific package, navigate to the package directory and run the same command.

End-to-End Tests

End-to-end tests simulate real user interactions with the system and are located in the /e2e/ directory of each package that includes them. Run all e2e tests with the following command:

npm run e2e

To run tests for a specific package, navigate to the package directory and run the same command.

When debugging e2e tests, you can set an environment variable to increase the Jest timeout:

E2E_DEBUG=true npm run e2e

This allows you to step through the tests without them failing due to timeouts.

Deployment and Release Process

Vendure uses Lerna's fixed mode for versioning and releasing packages. This approach simplifies the development process and ensures compatibility across all packages.

Release Process

  1. Run the publish script:
npm run publish-release

This script runs lerna publish, which prompts you to select the next version. It then builds all packages and generates changelog entries.

  1. Push the changes to Git:
git push origin master --follow-tags

Vendure avoids relying on Lerna to push the release due to the lengthy pre-push hook, which can invalidate the npm OTP and cause the publish to fail.

Community and Support

Vendure has an active community and offers several channels for support and collaboration:

  • Discord: Join the Vendure Discord server to connect with other developers and get answers to your questions.
  • GitHub: Report issues, contribute to the codebase, and follow development progress on the Vendure GitHub repository.
  • Documentation: Comprehensive documentation is available on the Vendure website, including guides, API references, and tutorials.

Conclusion

Vendure is a powerful and flexible headless commerce platform that leverages modern technologies to provide a robust solution for building custom e-commerce applications. Its focus on developer productivity, ease of customization, and modular architecture makes it an excellent choice for businesses looking to create unique and scalable online stores. By following the guidelines and best practices outlined in this guide, you can harness the full potential of Vendure and deliver exceptional e-commerce experiences.

Next Post Previous Post
No Comment
Add Comment
comment url