https://github.com/hex-digital/nuxt-datocms
A module for simplifying an advanced integration with DatoCMS. Simplifies getting and display content, draft previews, live update subscriptions, generating a sitemap, and more.
https://github.com/hex-digital/nuxt-datocms
Last synced: about 1 year ago
JSON representation
A module for simplifying an advanced integration with DatoCMS. Simplifies getting and display content, draft previews, live update subscriptions, generating a sitemap, and more.
- Host: GitHub
- URL: https://github.com/hex-digital/nuxt-datocms
- Owner: hex-digital
- License: mit
- Created: 2023-03-13T11:25:18.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-12-09T23:45:16.000Z (over 1 year ago)
- Last Synced: 2025-03-23T12:46:40.158Z (over 1 year ago)
- Language: TypeScript
- Homepage:
- Size: 1.5 MB
- Stars: 7
- Watchers: 3
- Forks: 2
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# Nuxt DatoCMS
[![npm version][npm-version-src]][npm-version-href]
[![npm downloads][npm-downloads-src]][npm-downloads-href]
[![License][license-src]][license-href]
[![Nuxt][nuxt-src]][nuxt-href]
Nuxt 3 module for [DatoCMS](https://datocms.com/), a wonderful Headless CMS.
- [✨ Release Notes](/CHANGELOG.md)
## Features
- ⛰ Integration with Nuxt's `useAsyncData()` for de-duplicated requests
- 🌲 Pre-configured preview mode for draft content, and real-time updates
- 👌 Auto-imports composables + components from [`vue-datocms`](https://github.com/datocms/vue-datocms)
- 🧭 Easily generate a sitemap for your DatoCMS-powered site (coming soon)
- ⚙️ Compatible with any data-fetching library (Villus, Apollo, axios, etc) (coming soon)
## Usage
_Note: This module is for Nuxt 3. We do not provide a Nuxt 2 version._
> If you are a first-time DatoCMS user, read the [Nuxt DatoCMS](https://www.datocms.com/cms/nuxtjs-cms) page
> to get a project ready in less than 5 minutes.
### Installation
1. Add `@hexdigital/nuxt-datocms` dependency to your project
```bash
npx nuxi@latest module add datocms
```
2. Add `@hexdigital/nuxt-datocms` to the `modules` section of `nuxt.config.ts`
```js
export default defineNuxtConfig({
modules: [
'@hexdigital/nuxt-datocms'
]
});
```
3. Configure the options for this module. If you want to enable viewing draft content, set the optional parameters too:
```js
export default defineNuxtConfig({
modules: [
'@hexdigital/nuxt-datocms'
],
datocms: {
publicReadOnlyToken: '',
// Optional - if you'd like to enable draft previews
privateDraftEnabledToken: '',
privatePreviewModePassword: 'showmethenewstuff', // A password required to enable draft previews
privatePreviewModeEncryptionSecret: '14e6f2b5ebefb46270ed411e916c452a377c70f5d548cb6b672ec40d7e1ab8ef', // A hash that is stored on the User's device once draft is enabled, to prove it's legitimate. Change this to turn-off all currently active draft previews
// Optional - if you'd like to allow user's to preview new content without needing to enter a password (beta documentation that's open for feedback, for example).
disablePreviewPassword: true, // defaults to false
// Optional - if you'd like to disable using the default server API routes for draft preview (so you can create your own, for example)
registerApiHandlers: false, // defaults to true
// Optional - do not include environment if you're not using environments, and usually no need to include endpoint either
// environment: 'production', // defaults to undefined
// endpoint: 'https://graphql.datocms.com',
},
});
```
API tokens can be generated inside of your project, in Settings > API tokens. See image below
That's it! You can now use Nuxt DatoCMS in your Nuxt app ✨
### Requesting content
This module exposes two main composables, `useAsyncDatoCms()` and `useDatoCms()`.
For most cases, we recommend using `useAsyncDatoCms()`. It's a wrapper around Nuxt's `useAsyncData()`, which allows
us to de-duplicate our requests when using SSR, amongst other benefits.
```
// pages/index.vue
// This module sets `toHead` and `useAsyncDatoCms` to be auto-imported by Nuxt, if you have this enabled, so these imports aren't needed
import { toHead } from 'vue-datocms';
import { useAsyncDatoCms } from '@hexdigital/nuxt-datocms';
import { homepageQuery } from '~/apis/dato-cms/graphql/queries/getHomepage';
const { data } = await useAsyncDatoCms({ query: homepageQuery });
// An example of using page data to set your SEO tags for the page
useHead(() => toHead(data.value?.homepage?._seoMetaTags || {}));
```
If you're not looking to use `useAsyncData()` at all, then you can use the `useDatoCms()` composable instead. The
behaviour is the same, just without the `useAsyncData()` wrapper around the fetch call.
## Module Development
```bash
# Install dependencies
pnpm install
# Generate type stubs
pnpm run dev:prepare
# Develop with the playground
pnpm run dev
# Build the playground
pnpm run dev:build
# Run ESLint
pnpm run lint
# Run Vitest
pnpm run test
pnpm run test:watch
# Release new version
pnpm run release
```
## Contributing
All contributions are welcome. Please see our [Contribution Guidelines](./CONTRIBUTING.md).
[npm-version-src]: https://img.shields.io/npm/v/@hexdigital/nuxt-datocms/latest.svg?style=flat&colorA=18181B&colorB=28CF8D
[npm-version-href]: https://npmjs.com/package/@hexdigital/nuxt-datocms
[npm-downloads-src]: https://img.shields.io/npm/dm/@hexdigital/nuxt-datocms.svg?style=flat&colorA=18181B&colorB=28CF8D
[npm-downloads-href]: https://npmjs.com/package/@hexdigital/nuxt-datocms
[license-src]: https://img.shields.io/npm/l/@hexdigital/nuxt-datocms.svg?style=flat&colorA=18181B&colorB=28CF8D
[license-href]: https://npmjs.com/package/@hexdigital/nuxt-datocms
[nuxt-src]: https://img.shields.io/badge/Nuxt-18181B?logo=nuxt.js
[nuxt-href]: https://nuxt.com