npm package: @ref_digital/datocms-llms-nuxt
Description: A Nuxt 3 module that automatically generates llms.txt files from DatoCMS content during the build process
Latest version: 1.0.0

# @lg2/datocms-llms-nuxt

A Nuxt 3 module that automatically generates `llms.txt` files from DatoCMS content during the build process. This module fetches content from DatoCMS using the Content Delivery API, extracts a specified field, and writes it to a public file that can be used for LLM training, documentation, or content discovery.

## Features

- 🔄 Automatically fetches content from DatoCMS during build
- 📝 Extracts and writes content to `llms.txt` (or custom path)
- 🔍 Flexible field extraction from various DatoCMS content structures
- 📊 Supports DatoCMS Structured Text fields
- 🌍 Supports multiple DatoCMS environments
- ⚠️ Graceful error handling with development mode support

## Installation

Install the package using your preferred package manager:

```bash
# npm
npm install @lg2/datocms-llms-nuxt

# yarn
yarn add @lg2/datocms-llms-nuxt

# pnpm
pnpm add @lg2/datocms-llms-nuxt
```

Then add it to your `nuxt.config.js`:

```js
export default defineNuxtConfig({
  modules: [
    '@lg2/datocms-llms-nuxt',
  ],
  datocmsLlms: {
    apiToken: process.env.DATOCMS_API_TOKEN,
    // ... other options
  },
})
```

## Configuration

The module accepts the following configuration options:

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `apiToken` | `string` | **Required** | Your DatoCMS API token (from environment variable) |
| `outputPath` | `string` | `'public/llms.txt'` | Relative path where the output file will be written |
| `fieldName` | `string` | `cLlms` | The field name to extract from DatoCMS content |
| `modelName` | `string` | `cCommon` | The DatoCMS model API key |
| `environment` | `string` | `'main'` | The DatoCMS environment name (defaults to main environment) |

### Example Configuration

#### Fetching a specific record by ID

```js
export default defineNuxtConfig({
  datocmsLlms: {
    apiToken: process.env.DATOCMS_API_TOKEN,
    outputPath: 'public/llms.txt',
    fieldName: 'cLlms',
    modelName: 'cCommon',
    environment: 'main',
  },
})
```

#### Fetching the first record with the field from a model type

```js
export default defineNuxtConfig({
  datocmsLlms: {
    apiToken: process.env.DATOCMS_API_TOKEN,
    outputPath: 'public/llms.txt',
    fieldName: 'cLlms',
    modelName: 'cCommon', 
  },
})
```

## How It Works

1. **Build Hook**: The module hooks into Nuxt's `build:before` and Nitro's `nitro:build:before` hooks
2. **GraphQL Query**: Fetches content from DatoCMS's Content Delivery API using GraphQL
3. **Field Extraction**: Extracts the specified field from the DatoCMS record:
   - Direct field: `record.llms`
   - Structured text fields (DatoCMS structured text format)
   - Markdown/text fields
4. **Content Handling**: Supports various content formats:
   - Plain strings
   - Structured text (extracts text content from DatoCMS structured text)
   - Markdown fields
5. **File Writing**: Writes the extracted content to the specified output path

## Environment Variables

Set the following environment variable:

```bash
DATOCMS_API_TOKEN=your-datocms-api-token
```

You can get your API token from your DatoCMS project settings under **Settings > API tokens**.

## DatoCMS Model API Keys

DatoCMS uses model API keys to identify content types in GraphQL queries. These are typically:
- Lowercase
- CamelCase for the model name
- Pluralized for "all" queries (e.g., `blogPost` → `allBlogPosts`)

To find your model API key:
1. Go to your DatoCMS project
2. Navigate to **Settings > Models**
3. Click on your model
4. Check the **API identifier** field

## Error Handling

- **Missing API Token**: The module will log a warning and skip generation if `DATOCMS_API_TOKEN` is not set
- **API Errors**: In development mode, errors are logged but don't fail the build. In production, errors will fail the build
- **Missing Field**: If the specified field is not found, a warning is logged and the build continues
- **GraphQL Errors**: GraphQL query errors are logged with detailed error messages

## Use Cases

- **LLM Training**: Generate training data files for language models
- **Documentation**: Create public documentation files from CMS content
- **Content Discovery**: Make site content discoverable by crawlers and AI tools
- **SEO**: Provide structured content for search engines and AI assistants

## Requirements

- Nuxt 3.x
- Node.js >= 18.0.0
- DatoCMS account with API access

## Development

The module uses Nuxt's module system and integrates with:
- `@nuxt/kit` for module definition
- `ofetch` for API requests
- Node.js `fs` module for file operations
- DatoCMS Content Delivery API (GraphQL)

## Troubleshooting

### File Not Generated

1. Check that `DATOCMS_API_TOKEN` is set correctly
2. Verify the `modelName` matches your DatoCMS model API identifier
3. Ensure the `fieldName` exists in your DatoCMS model
4. Check the build logs for error messages

### Wrong Content Extracted

1. Verify the field structure in your DatoCMS content
2. Check that the field contains the expected data format
3. For structured text fields, the module extracts plain text from the structured content
4. Review the extraction logic in the `extractLLMsField` function

### Build Fails in Production

- Ensure your DatoCMS API token has the correct permissions (read access)
- Verify the API endpoint is accessible (`https://graphql.datocms.com`)
- Check network connectivity during build
- Verify the model API key is correct (case-sensitive)
- Ensure the record is published (draft records require draft-enabled tokens)

### GraphQL Query Errors

- Verify your model API key matches exactly (DatoCMS is case-sensitive)
- Check that the field name exists in your model
- Ensure your API token has read permissions for the model
- For environment-specific queries, verify the environment name is correct

## DatoCMS API Documentation

For more information about DatoCMS APIs, see:
- [Content Delivery API](https://www.datocms.com/docs/content-delivery-api)
- [GraphQL API Reference](https://www.datocms.com/docs/content-delivery-api/graphql)

## License

MIT