Development setup
Set up a local development environment for creating Voyzu packages.
1. Prerequisites
Package development has the same prerequisites as a production installation; no additional development tooling is required. The best way to ensure you are set up correctly do develop Voyzu packages is to install Voyzu, e.g. in a temporary folder. To do this follow the production installation guide
2. Choose a package name
Every Voyzu package name must use the format @publisher/package-name. For example:
@voyzu/ice-creams@voyzu/core@acme/warehousing
Choose the directory in which you will develop your packages and navigate to it at the command line. The directory does not need to contain an existing project.
3. Install the development environment
Run:
npm exec --yes --package=github:chrisjameslennon/create-voyzu -- create-voyzu devThe command creates the root package.json and packages/ directory when they do not exist. It downloads the Voyzu Platform into .run/voyzu, creates the development runtime and installs its dependencies.
The disposable platform runtime is always downloaded from Voyzu's main branch. Development branch and tag overrides are not supported.
The resulting structure is:
Existing .env.local, .gitignore, package.json and package source are preserved.
4. Create the PostgreSQL database
Create an empty PostgreSQL database for the development environment. The examples in this guide use the name voyzu:
Record the database host, port, database name, username and password. The development installer does not create the PostgreSQL database itself.
5. Configure the environment
Open .env.local and replace CHANGE_ME in VOYZU_DATABASE_URL with the development database password:
If the database password contains reserved URL characters, URL-encode it.
The installer has already generated a unique VOYZU_AUTH_SECRET. Preserve that value: Voyzu uses it to sign and verify authentication session cookies.
Do not commit .env.local or disclose its contents.
6. Initialize Voyzu and create the bootstrap administrator
Initialize the preinstalled Voyzu packages and create the bootstrap administrator:
The local bootstrap credentials are:
The bootstrap administrator is only for initial setup. Sign in, create a named administrator with a strong unique password, verify that account can sign in, and delete the ADMIN user before exposing Voyzu to other users or a network.
7. Optionally install the Voyzu Ice Creams example package
Voyzu Ice Creams is a simple package for managing ice cream flavours. It is a best-practice example that illustrates many Voyzu patterns.
Install it from the official package repository:
The repository is downloaded into .package-sources/voyzu-packages. The package is copied into .run/packages/@voyzu/ice-creams; it is not linked into the local packages/ development workspace.
Start Voyzu:
Browse to http://localhost:3000, sign in using the bootstrap administrator and select Ice Creams from the top navigation.
8. Write your package
With the development environment set up, it is time to write your package. All packages must:
Reside in
packages/@publisher/package-name.Include a
package.jsonwhosenameexactly matches@publisher/package-name.Conform to the Voyzu Package Contract.
Contain
voyzu.package.ts.Contain at least one module, with every module conforming to the Voyzu Module Contract.
The directory structure and package.json name are both authoritative. For example, packages/@acme/warehousing must declare "name": "@acme/warehousing".
Create a package from the Ice Creams reference implementation with:
This creates packages/@acme/customer-orders, replaces spaces with dashes, removes the template repository's Git metadata, derives display labels, code identifiers, paths and SQL table names from customer-orders, and links the package into the development runtime. The command refuses to overwrite an existing package. Review the generated business terminology and package metadata before developing it further.
Follow Develop a new package for a practical walkthrough based on the Voyzu Ice Creams reference package.
9. Link your package into the Voyzu Platform
Install a package being developed locally into the runtime:
The command retains its existing name, but creates an ordinary physical runtime copy:
The command installs workspace dependencies, applies the package's database installation and composes it into Voyzu.
10. Run Voyzu
This will start the Next.js development server. Hot reloading is enabled, so any change you make to your package in /packages will be automatically mirrored into the .run directory and will appear in the application.
Run composition again after structural changes such as adding modules, routes, navigation or package exports:
To install every active package beneath the local packages/ directory for watched development, run:
11. Install your package
Voyzu packages are installed directly from GitHub, so they do not require an npm publishing step. Commit and push a conforming package to a Git repository using the standard packages/@publisher/package-name structure.
Then rom the root of an existing production Voyzu installation, you can install it with:
The command downloads or refreshes the repository, copies the selected package into .run/packages, applies its database installation and composes it into Voyzu.
You must have Git access to the repository when the package is not public.
12. Publish your package
Voyzu packages are installed directly from GitHub, so they do not require an npm publishing step. All that is required to publish your package is to make your GitHub repository public.
If you think your package may benefit other users of the Voyzu platform, raise a Github issue.
Further reading
For all package and platform commands, see Voyzu commands.
Last updated