This is an internal documentation. There is a good chance you’re looking for something else. See Disclaimer.
Development
Setup
Install Node
Warning
Node version per release
Node Version
Nice Versions
v20
3.6 - 3.10
v22
3.11 - 3.13
v24
3.14 - 3.16
v26
3.17 -
Install and enable Node Corepack.
Warning
Yarn is installed via package manager
Corepackfrom Node. Therefore do not install Yarn with a os package manager.corepackis bundled withnodeuntil version 24 and does not need to be installed manually. From version 25, it can be installed with the commandnpm install -g corepack.Setup environment variables
These environment variables are used in the
.yarnrc.ymlfile:Key
Value
Usage
FONTAWESOME_NPM_AUTH_TOKENansible vault
Mandatory - used for installing packages
With osx the variables can be added with:
launchctl setenv FONTAWESOME_NPM_AUTH_TOKEN {TOKEN}or with linux:
FONTAWESOME_NPM_AUTH_TOKEN={TOKEN}Make sure to check if the variable is available. Maybe a restart is required.
Clone
tocco-client:git clone git@gitlab.com:toccoag/tocco-client.git cd tocco-client yarn install
Setup
.envfile:yarn plop Env
Install VS Code on your machine. Useful plugins which you can install:
Prettier (more details)
ESLint (more details)
Vitest
Code Styleguide
Start a package
Note
Whenever you change branches you need to run yarn install.
yarn start --package={package-name} --backend={backend-url}
yarn start-widget --key={widget-config-key} --backend={backend-url}
Open http://localhost:3000 and wait for a finished build.
Hint
When starting a widget with yarn start-widget you can navigate to http://localhost:3000/wp for WordPress simulation or to http://localhost:3000/legacy for legacy cms simulation.
Note
start-widget command will retrieve the widget config and start the widget package automatically.
Otherwise the widget can be started with yarn start --package={widget-package-name} as well. But then de ./dev/input.json has to be filled in with dummy config data.
Note
Hot reloading will allow parts of the application to be live reloaded when the source code changes. Keep in mind that hot reloading will not work for sagas.
Optional parameters
|
Enable an alternative backend. E.g. master deployment of Tocco. (default: |
This command will locally start the admin and uses the master deployment as backend.
yarn start --package=admin --backend=https://master.tocco.ch
Make sure that the selected backend has both application properties nice2.web.cookie.sameSite=None and nice2.web.allowedRequestOrigins=http://localhost:3000 set.
Otherwise you will get CORS errors when trying to connect to it. By default, these properties are only set for our test customer installations.
Note
You can allow third party cookies in your browser settings which makes development easier. For example if you connect your local client to master.tocco.ch and you are already logged in, you don’t need to login again. This is also useful if you test the admin app in the storybook.
Deploy package to local backend
For testing purposes it’s useful to test a package (admin, action or widget) in production mode. Therefore it’s easiest to deploy the package to the locally cloned nice2.
yarn nice2:deploy-package --package={package-name}
This script gets the nice2 repository folder with the same tocco version and copies the generated production build inside the repo folder.
Warning
This script needs the environment variable NICE2_REPO_BASE_PATH. The NICE2_REPO_BASE_PATH can be added to the .env file inside the tocco-client root folder and has to be set to the parent folder of all nice2 repositories.
Note
The deploy package script for bundles can be extended with --app argument to define which apps should be bundled. The build time can be significantly decreased and it’s useful for testing purposes when only working on one or a few apps.
Example:
yarn nice2:deploy-package --package=widget-bundle --app=entity-browser --app=docs-browser
Storybook
It might be helpful to start up Storybook locally to test the current state of development. Most of the components or packages have a dedicated story to run them isolated. Storybook can be started with the following command:
# run against local nice2
yarn storybook
# run against https://master.tocco.ch
yarn storybook:master
Use BACKEND={BACKEND_URL} yarn storybook to enable an alternative backend.
Add new story file
suffix filename with
*.stories.jsadd package in
storieslist instorybook/main.js
Unit Tests
Tests are using following tools and libraries:
Vitest (test runner, assertions, mocks)
ReactTestingLibrary with the jest-dom matchers
redux-saga-test-plan for sagas
The configuration is in vitest.config.ts and build/vitest-setup.js in the root (no per-package config).
Spec files (*.spec.{js,jsx,ts,tsx}) are located next to the source and run through the same Babel config as the
webpack build.
yarn test # all tests
yarn test packages/actions/sms # only files matching the path
yarn test -t 'partial test name' # only tests matching the name
yarn vitest # watch mode
Tests are always run from the root, packages have no own test script or jest.config.js anymore.
See Unit Tests for how to write tests and Migration from Jest, chai and sinon for the differences to Jest, chai and sinon.
Note
In VS Code the current spec file can be debugged with the launch configuration Debug Current Vitest Test
(part of the repo in .vscode); the Vitest extension runs single tests. IntelliJ detects Vitest
automatically.
End-to-End Tests
End-to-End (e2e) tests are written and run with Cypress.
See Cypress (End-to-End-Tests) for more detailed information.
Code Generators
The project provides some code generators. Generators are developed with Plop and can be executed with:
yarn plop
There are the following generators:
Package
used for new packages, creates all file structure for a package
Env
used initially for set up the environment, initiate a .env file with your environment variables
Bundle app
used for adding a package to a bundle (e.g. a widget to the
widget-bundle)
Build bundle
Sometimes it’s desired to only build a package for testing purposes.
yarn compile:dev --package={package-name}
yarn compile:prod --package={package-name}
Parameters
|
Opens BundleAnalyzerPlugin to investigate the bundle sizes. |
|
To enable an alternative backend. |