@open-formulieren/formio-builder

Formio builder for Open Forms

This library implements the builder to build Form.io 4.13.x forms supporting the Open Forms extensions.

Documentation/demo

• Storybook documentation and reference.
• Shared types library documentation: @open-formulieren/types.

What is the purpose of this library?

Improving the developer experience for the Open Formulieren development team, by making the builder form definition more declarative and removing levels of abstraction, while maintaining re-use of components and common configurations.

We use third party form and validation libraries so that we can more easily reason about our form component configuration without being constrained by Formio.js itself. Using Typescript, we can also enforce certain behaviours at compile-time.

This library is NOT intended to be a competing library of Form.io's own form builder:

• it does not implement all the Form.io features, only the ones actively used and exposed in Open Forms
• it does not implement the Javascript API of Form.io's form builder, instead it provides the hooks needed by the Open Forms backend project

Contributing

Contributions that do not provide a direct benefit to the Open Forms project will unfortunately be rejected, as we do not have the ambition nor resources to maintain these.

For (code) contributions that do fit the goals of this library, please follow these guidelines:

• Create an issue with a description of the problem or required feature
• Reference the issue ID in commit messages and pull requests
• Functionality must be documented in Storybook
• Functionality must be covered by tests - Jest (unit/integration) tests and/or Storybook interaction tests

Getting started

• Clone the repository and then ensure you use the correct node version:

nvm use

• Install the dependencies

npm install

• Start Storybook in dev mode for component development:

npm run compilemessages
npm start

• Make code changes, check in Storybook, add tests... etc.

• Run the tests (Storybook needs to be running still!)

npm test

• Check that the (Typescript) build compiles cleanly:

npm run build:esm

Additional NPM scripts can be found in package.json.

Managing translations

Any user-facing literals should be defined as being translatable in the code.

To extract these messages, there are utility scripts, intended to be run from the root of the repository.

• ./bin/makemessages.sh - responsible for extracting translations from the code
• ./bin/find_untranslated_messages.py - useful to check if you missed any translations

Translations are shipped as assets in the NPM package, in the i18n folder. Downstream projects can include them from there.

Compilation

You can compile the messages using:

npm run compilemessages

This is required for Storybook, as the message catalog is loaded dynamically depending on the active locale.

Release flow

We don't let npm apply the git tags when releasing a new version, instead follow this process.

• Create a new branch release/x.y.z.
• Update the CHANGELOG.md file.
• Bump the version of the package as follows (use either major | minor | patch in the npm version command):

npm version --no-git-tag-version minor
git commit -am ":bookmark: Bump to version <newVersion>"

• Once this branch is merged into main, create a tag and push it:

git tag "<newVersion>"
git push origin main --tags

If you have GPG keys set up, you can use them for the git tag operation.

The CI pipeline will then publish the new version to npmjs.

Roadmap

See the roadmap issue.