A headless GraphQL ecommerce framework for the modern web
Switch branches/tags
Nothing to show
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
admin-ui feat(admin-ui): Add asset controls to ProductVariantsList Dec 11, 2018
codegen chore: Update to Prettier 1.15, run on all ts & html files Nov 20, 2018
docs/diagrams feat(server): Refine customer signup flow Nov 20, 2018
server feat(server): Add assets to ProductVariant Dec 11, 2018
shared feat(admin-ui): Add asset controls to ProductVariantsList Dec 11, 2018
.editorconfig chore: Set up root linting & formatting on commit Jul 11, 2018
.gitignore feat(server): Create barrel files for public exports Dec 6, 2018
.lintstagedrc.yml chore: Update to Prettier 1.15, run on all ts & html files Nov 20, 2018
.prettierignore feat(server): Convert auth to GraphQL, fix auth guard mechanism Sep 5, 2018
.prettierrc chore: Set up root linting & formatting on commit Jul 11, 2018
.travis.yml chore(server): Update jest, ts-jest and node versions Nov 21, 2018
CONTRIBUTING.md docs: Add MIT license, expand readme Jun 22, 2018
LICENSE docs: Add MIT license, expand readme Jun 22, 2018
README.md feat(server): Improved error handling Nov 22, 2018
graphql.config.json feat(admin-ui): Generate TypeScript types from api & client schemas Jun 29, 2018
package.json chore: Update to Prettier 1.15, run on all ts & html files Nov 20, 2018
schema.json feat(server): Add assets to ProductVariant Dec 11, 2018
tsconfig.json refactor: Configure shared path alias, move codegen into shared Aug 28, 2018
tslint.json style: Unify tslint configs and fix outstanding issues Jun 14, 2018
yarn.lock chore: Update to Prettier 1.15, run on all ts & html files Nov 20, 2018

README.md

Vendure Build Status

logo

A headless GraphQL ecommerce framework built on NestJS with TypeScript.

Status

Currently in pre-alpha, i.e. it is not yet useable.

Structure

Vendure is a headless framework, which means that it is just an API serving JSON via a GraphQL endpoint. The code for the server is located in the server directory.

We will ship with an administration UI which is a stand-alone web application which can be used to perform tasks such as inventory, order and customer management. The code for this is located in the admin-ui directory.

vendure/
├── admin-ui/       # Source of the admin ui app (an Angular CLI project)
├── codegen/        # Scripts used to generate TypeScript types from the GraphQL schemas & documents
├── docs/           # Documentation source (not much there yet)
├── server/         # Source for the Vendure server
├── shared/         # Types and utils shared by the server & admin ui

Development

Server

The server requires an SQL database to be available. I am currently using bitnami-docker-phpmyadmin Docker image, which is MariaDB including phpMyAdmin.

Vendure uses TypeORM, so it compatible will any database which works with TypeORM.

  • Configure the dev config
  • Create the database using your DB admin tool of choice (e.g. phpMyAdmin if you are using the docker image suggested above). Name it according to the config ("vendure-dev").
  • cd server && yarn
  • Populate mock data with yarn populate
  • yarn start:dev to start the server

Admin UI

Code Generation

graphql-code-generator is used to automatically create TypeScript interfaces for all GraphQL server operations and admin ui queries. These generated interfaces are used in both the admin ui and the server.

Run yarn generate-gql-types to generate TypeScript interfaces based on these queries. The generated types are located at ./shared/generated-types.ts.

Testing

Server Unit Tests

The server has unit tests which are run with the following scripts in the server directory:

  • yarn test - Run unit tests once
  • yarn test:watch - Run unit tests in watch mode

Unit tests are co-located with the files which they test, and have the suffix .spec.ts.

Server e2e Tests

The server has e2e tests which test the API with real http calls and against a real Sqlite database powered by sql.js. The tests are run with the following scripts in the server directory:

  • yarn test:e2e - Run e2e tests once
  • yarn test:e2e:watch - Run e2e tests in watch mode

The e2e tests are located in /server/e2e. Each test suite (file) has the suffix .e2e-spec.ts. The first time the e2e tests are run, sqlite files will be generated in the __data__ directory. These files are used to speed up subsequent runs of the e2e tests. They can be freely deleted and will be re-created the next time the e2e tests are run.

Admin UI Unit Tests

The Admin UI has unit tests which are run with the following scripts in the admin-ui directory:

  • yarn test --watch=false - Run unit tests once.
  • yarn test - Run unit tests in watch mode.

Unit tests are co-located with the files which they test, and have the suffix .spec.ts.

User Guide

Localization

Vendure server will detect the most suitable locale based on the Accept-Language header of the client. This can be overridden by appending a lang query parameter to the url (e.g. http://localhost:3000/api?lang=de).

All locales in Vendure are represented by 2-character ISO 639-1 language codes.

Translations for localized strings are located in the i18n/messages directory.

Errors

All errors thrown by the Vendure server can be found in the errors.ts file.

All errors extend from I18nError, which means that the error messages are localized as described above. Each error type has a distinct code which can be used by the front-end client in order to correctly handle the error.

Custom Fields

The developer may add custom fields to most of the entities in Vendure, which may contain any data specific to their business requirements. For example, attaching extra login data to a User or some boolean flag to a Product.

Custom fields can currently be added to the following entities:

  • Address
  • Customer
  • Facet
  • FacetValue
  • Product
  • ProductOption
  • ProductOptionGroup
  • ProductVariant
  • User

Custom fields are configured by means of a customFields property in the VendureConfig object passed to the bootstrap() function.

Example

bootstrap({
    port: API_PORT,
    apiPath: API_PATH,
    cors: true,
    jwtSecret: 'some-secret',
    dbConnectionOptions: {
        // ...
    },
    customFields: {
        Product: [
            { name: 'infoUrl', type: 'string' },
            { name: 'downloadable', type: 'boolean' },
            { name: 'shortName', type: 'localeString' },
        ],
        User: [
            { name: 'socialLoginToken', type: 'string' },
        ],
    },
})

When Vendure runs, the specified properties will be added to a customFields property of the Product and User entities, and the GraphQL schema will be updated to reflect the availability of these fields.

In the admin UI, there will be form inputs which allow these fields to be updated by an administrator.

Custom Field Types

Currently the supported types are:

type corresponding type in DB corresponding GraphQL type
string varchar String
localeString varchar String
int int Int
float double Float
boolean bool / tinyint Boolean
datetime datetime / timestamp String

Note that the "localeString" type can be localized into any languages supported by your instance.

The following types are under consideration:

  • blob
  • text

Planned extensions

Currently a custom field configuration has only a "name" and "type". We will be adding further configuration options in the future as the framework matures. Currently-planned options are:

  • Enum-like options for strings. This would display a <select> control with pre-defined values.
  • Access control based on user permissions. So that read / update access to a given custom field can be restricted e.g. only authenticated users / admins / not exposed via the GraphQL API at all (in the case where) the custom field will be used solely programatically by business logic contained in custom plugins).
  • Config for the controls in the admin UI. For example, an "int" field could have its "step", "max" and "min" values specified, which would add corresponding constraints in the admin UI.
  • Validation logic. It may be useful to allow the developer to pass a validation function for that field in the config, so that any specific constraints can be imposed on the inputted data in a consistent manner.
  • Custom UI Widget. For certain specialized custom fields, it may be desirable for the administrator to be able to use a custom-made form input to set the value in the admin UI. For example, a "location" field could use a visual map interface to set the coordiantes of a point. This would probably be a post-1.0 feature.

Orders Process

The orders process is governed by a finite state machine which allows each Order to transition only from one valid state to another, as defined by the OrderState definitions:

export type OrderState =
    | 'AddingItems'
    | 'ArrangingShipping'
    | 'ArrangingPayment'
    | 'OrderComplete'
    | 'Cancelled';

This process can augmented with extra states according to the needs of the business, and these states are defined in the orderProcessOptions property of the VendureConfig object which is used to bootstrap Vendure. Additional logic can also be defined which will be executed on transition from one state to another.

License

MIT