@datagouv/components-next

@datagouv/components

In this document, "the user" is the application using @datagouv/components (for example: cdata or udata-front-kit). For general project setup and development, see the main project README.

Usage

Config

@datagouv/components provides a Vue plugin to load the configuration.

import { datagouv } from '@datagouv/components-next'

app.use(datagouv, {
    name: 'data.gouv.fr', // Name of the site in some texts
    baseUrl: 'https://www.data.gouv.fr', // Used for redirects
    apiBase: 'https://www.data.gouv.fr', // Used for API calls (could default to `baseUrl`?)
})

Layout

To use the Toggletip component you should add a <div id="tooltips" /> in your layout.

Special functions and components (only for Nuxt)

Nuxt is a special environment (both server and browser) and requires some special functions and components to work.

import { TextClamp } from '#components'
import CdataLink from './components/CdataLink.vue'
import { datagouv, type UseFetchFunction } from '@datagouv/components-next'

const runtimeConfig = useRuntimeConfig()

app.vueApp.use(datagouv, {
    // These are the same as above…
    name: runtimeConfig.public.title,
    baseUrl: runtimeConfig.public.i18n.baseUrl,
    apiBase: runtimeConfig.public.apiBase,
    devApiKey: runtimeConfig.public.devApiKey,

    // ----------------------------------------
    // --- Special functions and components ---

    // Tell `@datagouv/components` to use `useFetch` from Nuxt instead of custom built-in.
    customUseFetch: useFetch as UseFetchFunction, 

    // Nuxt doesn't like `TextClamp` in the server, provides the client only `TextClamp`
    textClamp: TextClamp,

    // The following properties allow to provide components specific to Nuxt.

    // This `appLink` component will receive the raw link (without i18n prefix)
    // and needs to add it.
    appLink: CdataLink,
    
    // The ClientOnly allow to disable SSR for some components.
    clientOnly: ClientOnly,
})

CSS

@datagouv/components is using TailwindCSS and some DSFR right now. The user needs to provide the correct version of the DSFR. Concerning TailwindCSS, there are two modes:

• If the user is using TailwindCSS, it can import a full TailwindCSS config with @import "@datagouv/components-next/assets/main.css";, then build the CSS via TailwindCSS CLI or Vite plugin.
• If the user is not using TailwindCSS, it can import an already built CSS file with @import '@datagouv/components-next/dist/components.css';. Note @dev, this file should be built before publishing the package to NPM with npm run css. For more details on the technology stack, see the main README.

I18n

@datagouv/components is using vue-i18n to provide internationalisation. As always, there are two modes:

• If the user is using Nuxt, it can simply add the locales files in the nuxt.config.ts

{
    code: 'fr',
    language: 'fr',
    files: ['fr-FR.json', '../../node_modules/@datagouv/components-next/src/locales/fr.json'],
},

Nuxt is responsible for building the JSON file to the correct vue-i18n JS format.

• If the user is not using Nuxt, it should provide the i18n object to the datagouv Vue plugin. The plugin will then merge the already built messages's files.

Suspense

To work with Nuxt, some components are doing HTTP requests during the setup function (Nuxt can then do SSR for these requests: doing these requests server-side). These components need to be wrapped in a <Suspense> wrapper (you can even provide a #fallback). You can either wrap individual components inside <Suspense> or wrap your entire application/layout in <Suspense>

<Suspense>
    <DatasetInformationPanel v-if="dataset" :dataset="dataset" />
</Suspense>

Development

For general development guidelines and contributing, see the contributing section in the main README.

Code Linting and Formatting

This component library uses both ESLint and Prettier for code quality and formatting:

npm run lint    # Lint and auto-fix ESLint issues
npm run format  # Format code with Prettier

Note: Make sure to run both commands before submitting contributions to ensure consistent code style.

Config

You can use the config with the composable useComponentsConfig().

import { useComponentsConfig } from '../main'

const config = useComponentsConfig()

Special functions and components (only for Nuxt)

[!WARNING]
In @datagouv/components there are a few functions and components we cannot use directly:

• TextClamp component
• useFetch Nuxt function

To use these, you need to get them from the config or via special wrappers.

useFetch

import { useFetch } from '../functions/api'

const { data: allLicenses } = await useFetch<Array<License>>('/api/1/datasets/licenses/')

This wrapper will use the provided useFetch function from Nuxt or a custom built-in replacement (should work in most of the case but is a really simplify version of the Nuxt one).

TextClamp

Use the component from the config (could add a wrapper in the future to simplify this).

import { useComponentsConfig } from '../main'

const config = useComponentsConfig()

<component
    :is="config.textClamp"
    v-if="config && config.textClamp"
    class="fr-mx-1v"
    :auto-resize="true"
    :text="organization.name"
    :max-lines="1"
/>

[!NOTE]
Nuxt doesn't even allow to load the vue3-text-clamp library in the server so we need to use dynamic import in the plugin config to be sure it's only loaded on non-Nuxt environment.

Links

To do links in the application you can use the <AppLink> component. Not sure why it's required. Maybe we could always use a <RouterLink> from vue-router since every user is using vue-router? I think it's useful to add lang prefix to links but it's not done yet? Need testing.

Maybe this component shouldn't be exposed too, because I don't know why a user should use this instead of their own component (<RouterLink> or <CdataLink>…)

Release

This package is available as @datagouv/components-next on npm.

It follows the semantic versioning specification.

To make a new release, you have to :

• update the version
• publish to npm
• Commit and push the version change

Update the version

Use the dedicated npm command, with the correct parameter :

npm version VERSION

Where VERSION is :

• major when you make incompatible API changes
• minor when you add functionality in a backward compatible manner
• patch version when you make backward compatible bug fixes Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

Publish to NPM

npm run publish-stable

📄 License

This component library is licensed under the MIT License, which is the same as the main project. This allows for permissive usage of the components in other projects.

For more details, see the LICENSE file in the main project directory.