@datagouv/components-next

中文文档
1.5.0发布于 2026/11/17MITES Module近 30 天下载 5717

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.

原始使用文档
文档目录15 节
  1. Usage
  2. Config
  3. Layout
  4. Special functions and components (only for Nuxt)
  5. CSS
  6. I18n
  7. Suspense
  8. Development
  9. Code Linting and Formatting
  10. Config
  11. Special functions and components (only for Nuxt)
  12. Release
  13. Update the version
  14. Publish to NPM
  15. 📄 License

@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.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:

  1. 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.
  2. 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 PNPM with pnpm run css. For more details on the technology stack, see the main README.

I18n

@datagouv/components is using a few custom functions to provide internationalisation:

  • $t() inside templates
  • const { t } = useTranslation() inside JS
  • <TranslationT keypath="xxx"></TranslationT> for putting HTML inside text

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>
    <ActivityList />
</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:

pnpm run lint    # Lint and auto-fix ESLint issues
pnpm 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.

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 :

  1. update the version
  2. publish to npm
  3. Commit and push the version change

Update the version

Use the dedicated pnpm command, with the correct parameter :

pnpm 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

pnpm login
pnpm 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.

版本与发布记录

@datagouv/components-next 共发布 340 个版本,首次发布于 2025/04/30;过去 12 个月发布了 302 个版本。

版本发布日期距今
1.5.0latest2026/11/17今天
1.4.1-dev.1389.g02d6ad71dev2026/11/161 天前
1.4.1-dev.1386.g127f07d32026/11/125 天前
1.4.1-dev.1385.gdbe95e782026/11/125 天前
1.4.1-dev.1384.gab4fb9842026/11/125 天前
1.4.1-dev.1383.g24f4e1af2026/11/107 天前

关于 @datagouv/components-next 的常见问题

@datagouv/components-next 是什么?

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.

如何安装 @datagouv/components-next?

在项目目录运行 npm install @datagouv/components-next,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:vue(^3.5.13)、echarts(^6.0.0)、vue-router(^4.5.0 || ^5.0.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@datagouv/components-next 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/datagouv__components-next 是否存在。

@datagouv/components-next 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@datagouv/components-next 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >= 20.0.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@datagouv/components-next 可以商用吗?

@datagouv/components-next 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@datagouv/components-next 的下载量有多少?

根据 npm 官方下载统计,@datagouv/components-next 在 2026/10/12 – 2026/11/10 这 30 天内被下载 5,717 次,日均约 191 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@datagouv/components-next 还在维护吗?

最新版本 1.5.0 发布于 2026/11/17(今天);至今共发布 340 个版本,其中过去 12 个月发布了 302 个;首次发布于 2025/04/30。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。