Setting up a development environment

Requirements

You need:

  • Node.js 14. Unfortunately one of our dependencies are broken on Node 16. If you normally use Node 16, use nvm to temporarily switch to version 14. 
  • You may need some system packages. On Ubuntu 20.04 these packages are required or at least helpful: 
    • libpq-dev build-essential python-is-python3 postgresql-client git libsystemd-dev entr
  • Lerna. Install with npm install -g lerna
  • Nodemon. Install with npm install -g nodemon

Checkout and Install

Fork the Saltcorn repository (https://github.com/saltcorn/saltcorn) and checkout with ssh:

git clone [email protected]:{GITHUB_USERNAME}/saltcorn.git

now go to the saltcorn checked out repository and run

lerna bootstrap

to prepare the local build. You also need to run this every time you add a new dependency to one of the packages.

You should add /path/to/saltcorn/packages/saltcorn-cli/bin to your PATH. if you use bash, you can run

echo 'export PATH=$HOME/saltcorn/packages/saltcorn-cli/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

you should now be able to run the saltcorn command.

[email protected] saltcorn % saltcorn

Command-line interface for Saltcorn, open-source no-code platform

 

VERSION

  @saltcorn/cli/0.5.6-beta.3 darwin-x64 node-v14.16.1

 

USAGE

  $ saltcorn [COMMAND]

 

COMMANDS

  add-schema       Add Saltcorn schema to existing database

  backup           Backup the PostgreSQL database to a file with pg_dump or zip

  create-tenant    Create a tenant

  create-user      Create a new user

  ...

If you don't see this, then something has gone wrong.

Setup

You also need to tell salt how it will connect to a database. You can do this just by running

saltcorn setup

Select the development option which will use SQLite. Now you should be able to run with

saltcorn serve

Connect to http://localhost:3000 and set up your account

Development server

You are now ready to edit any of the files in the saltcorn repository. When you save a file, the server does not automatically pick up changes. You can press Ctrl+C to restart it, and then you should see your changes if you read out the page in the browser.

The nodemon tool make this process a bit easier. It can watch for file changes and restart the server automatically when it sees changes. To run the Saltcorn server with nodemon, run

nodemon  `which saltcorn` serve

Saltcorn uses one worker process per CPU core. This may slow down start-up if you have a lot of cores. To reduce the number of worker processes, set the SALTCORN_NWORKERS environment variable

SALTCORN_NWORKERS=2 nodemon  `which saltcorn` serve

If you launch Saltcorn like this, you only have to save your file and reload the page. You may have to wait a few seconds before you are able to reload the page.

Developing the builder

The drag-and-drop builder used to build pages and views is a React component which is compiled separately. Its source package is in packages/saltcorn-builder in the saltcorn repository. The build artefact is checked into version control and part of the saltcorn-builder NPM package as dist/builder_bundle.js. This is done to avoid needless rebuilds and to reduce the size of the node_modules installed. In the saltcorn-builder package, the build npm script can be used to rebuild this bundle, which is imported and statically served by the Saltcorn server process

To rebuild the builder bundle for the first time,

cd packages/saltcorn-builder

npm install

npm install [email protected]

npm run build

This regenerates dist/builder_bundle.js. Subsequent builds can be performed with

npm run build

You can also perform a development build, which is faster to build, gives you better error messages but a larger bundle

npm run builddev

Running either the production or the development build will be picked up if you are running a nodemon saltcorn server in a different terminal window.

In order to get continuous builds, without needing to re-run the build script manually, you can use the entr tool (installed through your OS package manager):

git ls-files | entr npm run builddev

in the saltcorn-builder directory. If you run the nodemon process in one terminal window and the above command in a different terminal window, you should see any changes after saving a source file and reloading the page. This is a little bit slower as both the rebuild needs to finish and the server need to reload.