WB Storyblok Nuxt Redirects

A Nuxt module that handles URL redirects using Storyblok datasources. This module fetches redirect rules from a Storyblok datasource and applies them either at build time or runtime. This module is part of a Storyblok App Extension which manages auto-deployment/reload and the datasource in Storyblok.

Features

• 🚀 Build-time redirects - Generate static route rules at build time for optimal performance
• ⚡ Runtime redirects - Dynamically fetch and apply redirects at runtime
• 🔄 Hot reload support - Refresh redirects without restarting the server using a secure token
• 📦 Storyblok integration - Manage redirects directly in Storyblok's datasource editor
• 🔍 Efficient lookup - Uses binary search for fast redirect matching

Installation

# Using npm
npm install @wb-at/storyblok-nuxt-redirects
# Using yarn
yarn add @wb-at/storyblok-nuxt-redirects
# Using pnpm
pnpm add @wb-at/storyblok-nuxt-redirects

Configuration

Add the module to your nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['@wb-at/storyblok-nuxt-redirects'],

  storyblokNuxtRedirects: {
    // Your Storyblok access token (required)
    storyblokAccessToken: 'your-storyblok-access-token',
    
    // Slug of the Storyblok datasource containing redirects (default: 'sb-wb-redirects')
    datasourceSlug: 'sb-wb-redirects',
    
    // If true, redirects are only generated at build time (default: false)
    buildTimeOnly: false,
    
    // Enable debug logging (default: false)
    debug: false,
    
    // Optional token to secure the refresh endpoint
    refreshToken: 'your-secret-refresh-token',
  },
})

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | storyblokAccessToken | string | - | Your Storyblok API access token (required) | | datasourceSlug | string | 'sb-wb-redirects' | The slug of the Storyblok datasource containing redirects | | buildTimeOnly | boolean | false | When true, redirects are fetched at build time only | | debug | boolean | false | Enable debug logging | | refreshToken | string | - | Token to secure the redirect refresh mechanism |

Environment Variables

You can also configure the module using environment variables:

| Environment Variable | Description | |---------------------|-------------| | NUXT_PUBLIC_STORYBLOK_ACCESS_TOKEN | Storyblok access token | | NUXT_PUBLIC_STORYBLOK_NUXT_REDIRECTS_BUILD_TIME_ONLY | Build time only mode | | NUXT_PUBLIC_STORYBLOK_NUXT_REDIRECTS_DATASOURCE_SLUG | Datasource slug | | NUXT_PUBLIC_STORYBLOK_NUXT_REDIRECTS_DEBUG | Debug mode | | NUXT_STORYBLOK_NUXT_REDIRECTS_REFRESH_TOKEN | Refresh token (private) |

Usage Modes

Runtime Mode (Default)

In runtime mode, redirects are fetched from Storyblok on the first request and cached. A global middleware handles redirect matching for all incoming requests.

storyblokNuxtRedirects: {
  buildTimeOnly: false // This is the default
}

Build-time Mode

In build-time mode, redirects are fetched during the Nuxt build process and added as static route rules. This provides the best performance but requires a rebuild to update redirects.

storyblokNuxtRedirects: {
  buildTimeOnly: true,
}

Refreshing Redirects at Runtime

When running in runtime mode, you can refresh the cached redirects by making a request with the refresh token in the Authorization header:

curl -X GET https://your-site.com/any-page \
  -H "Authorization: Bearer your-secret-refresh-token"

This will trigger a reload of redirects from Storyblok without requiring a server restart.

Development

# Install dependencies
yarn install

# Prepare development environment
yarn dev:prepare

# Start development server with playground
yarn dev

# Run tests
yarn test

# Build the module
yarn prepack