@gouvfr-lasuite/integration

@gouvfr-lasuite/integration npm package

The @gouvfr-lasuite/integration npm package helps services of La Suite numérique with already-made React and HTML templates of common La Suite UIs.

For now, it helps developers integrate:

• a La Suite branded homepage
• the Gaufre ("waffle") button that lets users of a service easily switch between La Suite services.

Usage

npm install @gouvfr-lasuite/integration

If you use React, you can directly consume the exposed React components.

If you use anything else, you can copy and paste content from the HTML templates in the dist/html folder.

CSS is also available. Depending on whether or not you use the DSFR, you can use different CSS files from dist/css.

Precise documentation on usage is available on integration.lasuite.numerique.gouv.fr.

Development

This folder is meant to generate the @gouvfr-lasuite/integration npm package.

It's a vite app.

To start, npm install a first time and copy the example env file: cp .env.example .env. Make sure the API env var targets a running API. If you don't want to use the production one, you can run one locally easily: the API is exposed via the /website server, go check the README there.

Then, run the local dev server with npm run dev.

The main dev file is src/dev/dev.tsx where a small testing React router is used to render the different React components while developing.

Building

Run npm run build to build all the dist/ files which are: React components, CSS files and HTML templates.

Internally, building all of this is a bit different than your usual vite app. We actually use 3 vite configs, and running npm run build runs them all:

React components

The default build generates the React components in es6 and commonjs files with the vite "lib" mode. Everything in src/index.ts is exposed in the generated file.

CSS

The css-config build generates the CSS files. They all go through purgecss. The list of CSS files to generate is in the css vite config.

CSS is rendered like that, and not through the main vite config, because CSS rendering in lib mode doesn't allow us to easily generate multiple CSS files while using the postcss-config.

HTML files

The html-config generates the HTML files.

HTML files are not written by hand: they are generated from the React components. The html vite config checks the src/html.tsx file and renders HTML files for every template listed.

Publishing a new npm package

• run npm version with either major, minor or patch to bump the version. There is no precise versioning strategy for now, but following semver is a good idea. So: breaking changes should be major updates, new features should be minor updates and bug fixes should be patch updates.
• add a new entry in the CHANGELOG.md file to describe the changes.
• :warning: make sure your local .env file uses production values.
• run npm pack to generate a new tarball locally. It's an easy to verify manually that the package is good before publishing it.
• run npm publish to publish the package on npm.
• commit your changes.
• create a git tag on this new commit: integration-vX.X.X.
• push the main branch and the new tag on github.