---
title: "Persistent Storage"
description: "Configure persistent storage for build assets across deployments."
canonical_url: "https://nuxtseo.com/docs/skew-protection/guides/storage-configuration"
---

> Index of every page on this site: [llms.txt](https://nuxtseo.com/llms.txt)

Nuxt Skew Protection needs persistent storage to preserve previous build assets across deployments.

The default storage path is `node_modules/.cache/nuxt-seo/skew-protection`. If your CI pipeline clears this directory, restore it before each build.

## Retention Periods

Set retention limits with [`retentionDays`](https://nuxtseo.com/docs/skew-protection/api/config#retentiondays-number) and [`maxNumberOfVersions`](https://nuxtseo.com/docs/skew-protection/api/config#maxnumberofversions-number). The defaults keep up to 10 versions for 30 days.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  skewProtection: {
    // Keep versions for 45 days
    retentionDays: 45,
    // Keep maximum 15 versions
    maxNumberOfVersions: 15
  }
})
```

Cleanup happens **during build**, removing:

- Versions older than `retentionDays`
- Oldest versions beyond `maxNumberOfVersions`

Before restoring assets, cleanup removes expired history and keeps the current release, even after its retention period.
The build uploads every required object before publishing its version manifest.
If an upload fails, the build fails and the previous manifest stays usable.
Missing assets in retained releases still fail the build.

New uploads use content hashes as storage keys, so unchanged bytes share one object across builds.
Cleanup deletes a shared object only after no retained release references it.
Existing version-prefixed objects remain readable.
After the first build writes shared objects, older module versions cannot restore those entries from the same store.

Exclude shared objects under `blobs/` from age-based bucket lifecycle deletion.
An old object can still serve the current release when later builds reuse its bytes.
Use the module's retention cleanup to remove these objects.

Before each upload batch, the module records its object keys in storage.
With strong reads, the next build removes abandoned uploads that never reached a manifest write.
Successful publications use their confirmed manifest for cleanup.
Recovery covers objects recorded by this module version. Older abandoned objects have no recovery record.
Delayed asset or journal writes can leave objects outside automatic recovery.
Retain `pending-uploads.json`, `asset-operations/`, and `asset-operation-completions/` between builds.
Exclude these records from bucket lifecycle deletion. They track recovery candidates and unresolved requests.
Deleting operation records can remove safeguards against delayed writes or deletes.
Operation records remain outside version retention and can accumulate across builds.

Memory and filesystem drivers use strong reads by default.
Other drivers default to `readConsistency: 'eventual'` and retain shared objects instead of deleting them automatically.
Set `skewProtection.storage.readConsistency: 'strong'` only when uncached reads immediately reflect completed writes.
[R2](https://developers.cloudflare.com/r2/reference/consistency/) and [Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html#ConsistencyModel) provide strong consistency for direct object API calls.
Do not enable strong mode through a cache, a replica, or an eventually consistent driver.

A failed request can still finish later. Strong reads do not prove the outcome of an earlier timed-out write.
The module retains objects referenced by uncertain manifest writes.
It avoids reusing storage keys whose deletion remains uncertain; later uploads use a separate key.
An operator must reconcile uncertain requests before deleting their objects.

## Build concurrency

Run one build at a time for each storage namespace. The module does not provide a distributed lock.
Give each app its own namespace. If builds share a namespace, serialize their complete build and deployment workflows.
Overlapping builds can overwrite the version manifest or delete objects another build has reused.

For GitHub Actions, set a constant concurrency group for the shared store:

```yaml [your-github-workflow.yml]
concurrency:
  group: skew-protection-production
  cancel-in-progress: false
```

Use the same group across all workflows and branches that write to that store.
[GitHub](https://github.com) concurrency groups apply within one repository.
Coordinate writers from other repositories or local builds separately.
See [GitHub's concurrency rules](https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/control-workflow-concurrency).

## GitHub Actions

The default filesystem storage works with GitHub Actions caching to persist build assets between deployments
using the `actions/cache` GitHub Action.

::warning
The cache key must be unique per deployment, otherwise `actions/cache` won't save new assets (it only saves on cache miss).
::

```yaml [your-github-workflow.yml]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      # Install...
      - name: Cache for Nuxt SEO
        uses: actions/cache@v4
        with:
          path: node_modules/.cache/nuxt-seo
          key: nuxt-skew-${{ github.sha }}
          restore-keys: |
            nuxt-skew-
      # Build, etc..
```

The `restore-keys` fallback restores previous assets. A unique `github.sha` key lets the cache save new assets after each build.

## Cloudflare

If you have your deployments running through [Cloudflare](https://cloudflare.com) then the `node_modules` folder should automatically persist between deployments, so you do not need any additional configuration.

If you're deploying to Cloudflare using your own CI pipeline, you can use Cloudflare KV storage to persist build assets instead. See the dedicated [Cloudflare Deployment](https://nuxtseo.com/docs/skew-protection/providers/cloudflare) guide which covers storage configuration in detail.

## Redis

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  skewProtection: {
    storage: {
      driver: 'redis',
      readConsistency: 'strong', // Requires reads from the primary
      host: process.env.REDIS_HOST || 'localhost',
      port: Number(process.env.REDIS_PORT) || 6379,
      password: process.env.REDIS_PASSWORD,
      db: 0,
      base: 'skew-protection'
    }
  }
})
```

## Upstash Redis

For serverless deployments like [Netlify](https://netlify.com) or [Vercel](https://vercel.com), [Upstash](https://upstash.com/) provides a Redis-compatible database with an HTTP API.

Install the Upstash [Redis](https://redis.io) client:

```bash [Terminal]
npx nypm add @upstash/redis
```

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  skewProtection: {
    storage: {
      driver: 'upstash',
      url: process.env.UPSTASH_REDIS_REST_URL,
      token: process.env.UPSTASH_REDIS_REST_TOKEN,
      base: 'skew-protection'
    }
  }
})
```

You can find your REST URL and token in the [Upstash Console](https://console.upstash.com/) after creating a database.

## CDN Usage

If your CDN already keeps `/_nuxt/**` assets available across deployments, you can disable asset bundling with [`bundleAssets`](https://nuxtseo.com/docs/skew-protection/api/config#bundleassets-boolean).

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  skewProtection: {
    // Disable persistent storage
    bundleAssets: false
  }
})
```

## Docker

A Docker build starts from a clean filesystem, so the default store at `node_modules/.cache/nuxt-seo/skew-protection` is discarded with the build container and every build begins empty. Keep it on a BuildKit cache mount in the stage that runs the build:

```dockerfile [Dockerfile]
FROM node:26-alpine AS build
WORKDIR /app
COPY . .
RUN --mount=type=cache,id=nuxt-seo-skew,sharing=locked,target=/app/node_modules/.cache/nuxt-seo \
    npm run build
```

::note
Cache mounts require BuildKit. It is the default engine in current Docker versions and on most build services, though some platforms need it selected explicitly.
::

For the `WORKDIR /app` above, the mount target is `/app/node_modules/.cache/nuxt-seo`. If you configure a different storage `base`, mount that path instead.

A cache mount only survives if the builder keeps its cache between builds; builds that always start cold should use [Redis](#redis) instead.

::warning
Always give the mount an `id`. Without one, BuildKit keys the mount by its target path, so every project built on the same machine or builder shares a single store and restores each other's assets into its output.

Use `sharing=locked` so concurrent builds cannot write to the store at once. Each build rewrites the version manifest from what it read at the start and prunes assets outside the retention window, so two builds sharing the directory can drop each other's release or delete assets the other is still restoring.
::

::note
The cache mount never enters the final image. Only the assets restored into the build output do, so retention adds to image size as well as cache usage. Trim it with [`retentionDays`](#retention-periods) and [`maxNumberOfVersions`](#retention-periods).
::

Avoid `--no-cache` and `--no-cache-filter` when checking retention. Both reset the mount, so the build stores a first release instead of restoring the previous one. Rebuild after a real source change instead, as a deployment would.

## Sitemap

See the full [sitemap](https://nuxtseo.com/sitemap.md) for all pages.
