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

# @lg2/storyblok-llms-nuxt

A Nuxt 3 module that automatically generates `llms.txt` files from Storyblok CMS content during the build process. This module fetches content from Storyblok, 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 Storyblok CMS during build
- 📝 Extracts and writes content to `llms.txt` (or custom path)
- 🔍 Flexible field extraction from various Storyblok content structures
- ⚠️ Graceful error handling with development mode support

## Installation

Install the package using your preferred package manager:

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

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

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

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

```js
export default defineNuxtConfig({
  modules: [
    '@lg2/storyblok-llms-nuxt',
  ],
  storyblokLlms: {
    accessToken: process.env.STORYBLOK_ACCESS_TOKEN,
    // ... other options
  },
})
```

## Configuration

The module accepts the following configuration options:

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `accessToken` | `string` | **Required** | Your Storyblok access token (from environment variable) |
| `outputPath` | `string` | `'public/llms.txt'` | Relative path where the output file will be written |
| `fieldName` | `string` | `'llms'` | The field name to extract from Storyblok content |
| `modelName` | `string` | `'common'` | The Storyblok story slug/model name to fetch |
| `language` | `string` | `'en'` | The language code to fetch from Storyblok |

### Example Configuration

```js
export default defineNuxtConfig({
  storyblokLlms: {
    accessToken: process.env.STORYBLOK_ACCESS_TOKEN,
    outputPath: 'public/llms.txt',
    fieldName: 'llms',
    modelName: 'config',
    language: 'en',
  },
})
```

## How It Works

1. **Build Hook**: The module hooks into Nuxt's `build:before` and Nitro's `nitro:build:before` hooks
2. **API Fetch**: Fetches content from Storyblok's CDN API using the configured story/model
3. **Field Extraction**: Searches for the specified field in multiple possible locations:
   - Direct field: `content.llms`
   - Component body: `content.body[].llms`
   - Configuration object: `content.configuration.llms`
4. **Content Handling**: Supports various content formats:
   - Plain strings
   - Markdown fields (`content`, `text`, or `markdown` properties)
5. **File Writing**: Writes the extracted content to the specified output path

## Storyblok Content Structure

The module looks for the `llms` field (or your custom `fieldName`) in the following locations:

### Option 1: Direct Field
```json
{
  "content": {
    "llms": "Your content here..."
  }
}
```

### Option 2: In Component Body
```json
{
  "content": {
    "body": [
      {
        "component": "some-component",
        "llms": "Your content here..."
      }
    ]
  }
}
```

### Option 3: In Configuration
```json
{
  "content": {
    "configuration": {
      "llms": "Your content here..."
    }
  }
}
```

## Environment Variables

Set the following environment variable:

```bash
STORYBLOK_ACCESS_TOKEN=your-storyblok-access-token
```

## Error Handling

- **Missing Access Token**: The module will log a warning and skip generation if `STORYBLOK_ACCESS_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

## 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

## 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

## Troubleshooting

### File Not Generated

1. Check that `STORYBLOK_ACCESS_TOKEN` is set correctly
2. Verify the `modelName` matches your Storyblok story slug
3. Ensure the `fieldName` exists in your Storyblok content
4. Check the build logs for error messages

### Wrong Content Extracted

1. Verify the field structure in your Storyblok content
2. Check that the field contains the expected data format
3. Review the extraction logic in the `extractLLMsField` function

### Build Fails in Production

- Ensure your Storyblok access token has the correct permissions
- Verify the API endpoint is accessible
- Check network connectivity during build

## License

MIT