Streamline getting started experience

[michaelbromley]

Our @vendure/create package is used to set up new Vendure projects. It is also used by developers looking to quickly try out Vendure for themselves.

It uses a series of prompts to collect the required information to scaffold a project directory with the correct configuration.

Current flow

Issues

• Sql.js is just not needed and can be removed to simplify the options & the code
• When using mysql/postgres, there are many steps to go through that add complexity to getting started:
  • You need to already have a DB server running somewhere
  • You need to manually create the database
  • You need to know the DB user credentials
• There is long pause after "Generated app scaffold" with no spinner. Some sync blocking work must be happening here.
• There are some reports of failures during install that seem related to native modules, especially Sharp. These are difficult to reproduce.

Improved flow

We should aim to cut down the number of steps to an absolute minimum. Therefore we should have 2 flows:

• Quick start: select which DB to support, and that's it. Everything else is automated. We use Docker to create a DB server instance for you locally.
• Manual config: Like the current flow, with the possibility of adding other configurable options, eg ID strategy (it is hard to change later to UUIDs)

So the quick start would consist of just these steps:

1. npx @vendure/create my-shop
2. Select DB type
3. ...??
4. profit

Docker detection

In the "quick start" flow:

We need to detect whether docker is running locally. Something like executing docker -v and testing the result / catching the error would probably suffice.

If docker is not detected, we can possibly try to start it automatically (research this), or at least prompt the user to start it and try again. If docker is simply not available, we could either 1) default to SQLite or 2) put user into the custom flow.

[dlhck]

Let's remove the DB step also in that quick start - is it really necessary to choose a DB type to experience Vendure? My answer would be no. We generally tend to recommend to use Postgres, so that quick start should also use that. Everything else should be configurable via interactive prompts or non-interactive options (e.g. --db=postgres)

It should also automatically start server and worker after scaffolding the new Vendure installation.

[michaelbromley]

Flow chart of the new process:

flowchart TD
    A[Start] --> B{Prompt: Quick Start or Manual Configuration}
    
    B -->|Quick Start| C{automated check: Is Docker running?}
    C -->|Yes| D[Continue with installation]
    C -->|No| E[Attempt to start Docker]
    E --> F{Could Docker be started?}
    F -->|Yes| D
    F -->|No| G[Install with SQLite]
    G-->D

    B -->|Manual Configuration| H[Select DB]
    H --> I[Enter credentials etc as with current flow]
    I --> D[Continue installation]

    D --> Z[End]

Loading

[Draykee]

Maybe we can also provide two setups in the quick config: production vs development.

• Production: focus more on the deployment, and configuration, migration script for initial configuration
• Development: focus more on some tools being installed like the CLI, Sql.js, default log level to verbose, etc.

[michaelbromley]

@Draykee With the quick config we are aiming to reduce the number of prompts/steps to an absolute minimum.

But I agree that there is room for improvement with tooling & setup for prod & dev. This is actually something we are thinking of rolling into the Vendure CLI. For example:

• Dev Command for Integrated Development Experience #3086

The goal is to get to the point where every common task is one CLI command away - dev, build, deploy.

[DanielBiegler]

I think I vaguely remember the script failing only after putting in all of the prompts because the folder already existed. Would be nice to check beforehand to save having to rerun everything. I may misremember its been a while.

Also the Dockerfile could generally be made leaner by multi staged builds that only copy over actually built artifacts instead of copying everything for example.

[dlhck]

@DanielBiegler improvements to all things Docker are coming. I am already cooking something! 🧑‍🍳

[mschipperheyn]

I would not use SQLite as a Docker default db, given that it has limitations in terms of what it can do. I would use Postgres. My guess is: if you don't use a production level database, you will open up a whole stream of issues on github with things that don't work as expected because it's SQLLite.

Based on the input choice, we could actually pull and install the database server if it's not found. On our installation we have a yarn command for that using docker-compose (we also install all related servers, such as in our case Gotify). That way, you blow through the database installation and make it even more seamless.

[dlhck]

@mschipperheyn it is Postgres actually. SQLite is just a fallback in case Docker is not installed or cannot be started (automatically and manually)