Vercel

You can use the Vercel Marketplace to add compatible storage to your project (Postgres, Turso, Redis, Vercel Blob, etc.).

Cloudflare

You can deploy your project on your own Cloudflare account, you need to create the necessary resources in your account and configure your project to use them (D1, KV, R2, etc.).

Then, create a Cloudflare Workers project and link your GitHub or GitLab repository.

Once your project is created, open the Settings tab and set:

• Bindings
  • KV namespace: KV and select your KV namespace created
  • KV namespace: CACHE and select your KV namespace for caching created
  • R2 bucket: BLOB and select your R2 bucket created
  • D1 database: DB and select your D1 database created

Then make sure to create the following wrangler.jsonc file in the root of your project:

{
  "$schema": "node_modules/wrangler/config-schema.json",
  // if hub.db is enabled
  "d1_databases": [
    {
        "binding": "DB",
        "database_name": "<database-name>",
        "database_id": "<database-id>"
      }
    ],
  // if hub.blob is enabled
  "r2_buckets": [
    {
        "binding": "BLOB",
        "bucket_name": "<bucket-name>"
    }
  ],
  "kv_namespaces": [
    // if hub.kv is enabled
    {
      "binding": "KV",
      "id": "<kv-namespace-id>"
    },
    // if hub.cache is enabled
    {
      "binding": "CACHE",
      "id": "<cache-namespace-id>"
    }
  ]
}

Cache

When self-hosting and using devtools for cache management (viewing/deleting cache entries), you need to configure additional environment variables:

In your Cloudflare project, go to Settings → Environment Variables and add:

Workers Builds

If deploying to Cloudflare Workers, you can use Workers Builds to automatically deploy your project on every commit.

Pages CI

If deploying to Cloudflare Pages, you can use Pages CI to automatically deploy your project on every commit.

NuxtHub Admin (Deprecated)

The NuxtHub Admin is made to simplify your experience with NuxtHub, enabling you to effortlessly manage teams and projects, as well as deploying NuxtHub application with zero-configuration on your Cloudflare account.

Production vs Preview Deployments

NuxtHub supports two types of deployments: production and preview.

Production Deployments

• When setting up your project, you can specify a production branch (defaults to main)
• Successful deployments to the production branch will be:
  • Accessible via your primary domain
  • Also available at <commit>.<project>.pages.dev

Preview Deployments

• Any deployment from a non-production branch (including pull requests) is considered a preview
• Successful preview deployments are accessible via:
  • <commit>.<project>.pages.dev
  • <branch>.<project>.pages.dev

NuxtHub CLI (Deprecated)

Deploy your local project with a single command:

npx nuxthub deploy

The command will:

1. Ensure you are logged in on admin.hub.nuxt.com
2. Make sure you linked your Cloudflare account
3. Link your local project with a NuxtHub project or help you create a new one
4. Build your Nuxt project with the correct preset
5. Deploy it to your Cloudflare account with all the necessary resources (D1, KV, R2, etc.)
6. Provide you with a URL to access your project with a free <my-app>.nuxt.dev domain

Usage with CI/CD

To integrate the nuxthub deploy command within your CI/CD pipeline, set the following environment variables:

• NUXT_HUB_PROJECT_KEY – Your project key available in:
  • Your project settings in the NuxtHub Admin
  • Your .env file (if you ran npx nuxthub link)
• NUXT_HUB_USER_TOKEN – Your personal token, available in User settings → Tokens in the NuxtHub Admin

Example command:

NUXT_HUB_PROJECT_KEY=<my-project-key> NUXT_HUB_USER_TOKEN=<my-user-token> npx nuxthub deploy

This will authenticate your user and link your NuxtHub project for deployment.

GitHub Action (Deprecated)

After linking a GitHub repository to your project, NuxtHub automatically adds a GitHub Actions workflow to automatically deploy your application on every commit using the NuxtHub GitHub Action.

NuxtHub integrates with GitHub deployments. This allows you to:

• View deployment statuses within GitHub
• Setup deployment concurrency
• Require approvals for deploying to environments

After deploying from a pull request, NuxtHub automatically adds a comment with information about the deployment.

Default workflow

The GitHub Workflow added to your repository is automatically tailored to your project's package manager. This is an example of a workflow added for a project using pnpm.

We support pnpm, yarn, npm and Corepack. If you use a different package manager, you can customise the generated nuxthub.yml GitHub Action.

name: Deploy to NuxtHub
on: push

jobs:
  deploy:
    name: "Deploy to NuxtHub"
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write

    steps:
      - uses: actions/checkout@v4

      - name: Install pnpm
        uses: pnpm/action-setup@v4
        with:
          version: 10

      - name: Install Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 24
          cache: 'pnpm'

      - name: Install dependencies
        run: pnpm install

      - name: Build & Deploy to NuxtHub
        uses: nuxt-hub/action@v2

Options

Inputs

The following input parameters can be provided to the GitHub Action. Learn more about Workflow syntax for GitHub Actions on GitHub's documentation.

Outputs

The GitHub Action provides the following outputs that you can use in subsequent workflow steps.

Environment Variables & Secrets

The NuxtHub GitHub Action builds the Nuxt application using build-time environment variables and secrets specified within NuxtHub Admin.

Setup

Creating a new project

When creating a new project from a template, or importing a Git repository, the GitHub Action workflow will automatically be set up for you.

Linking a repository to existing projects

Link your project to a GitHub repository within NuxtHub Admin → Projects → <Your Project> → Settings → General → Git Repository

Migration from Cloudflare CI to GitHub Actions

Migrate your project to GitHub Actions within NuxtHub Admin → Projects → <Your Project> → Settings → General → Git Repository → Begin Migration.

Monorepo setup

Our GitHub integration supports deploying multiple applications from the same repository.

When linking a Git repository, set "project root directory" to the base folder of your Nuxt application corresponding to that NuxtHub project.

When a repository is already linked to at least one project, additional projects linked will have the generated GitHub Actions workflow named nuxthub-<projectSlug>.yml.

Current limitations

• Separate applications should be deployed using different workflow jobs.

GitLab CI (Deprecated)

This section will guide you to implement the GitLab CI. The integration with GitLab CI builds on the Usage with CI/CD section, make sure you have those two variables NUXT_HUB_PROJECT_KEY and NUXT_HUB_USER_TOKEN.

User Token Variable

1. Open your Repository (on GitLab) > Settings > CI/CD > Variables
2. Click on Add variable
3. Set Visibility to Masked and hidden
4. Remove protected Flag (since we may use this variable also on non-protected branches)
5. Give a Key name = NUXT_HUB_USER_TOKEN
6. Paste your NUXT_HUB_USER_TOKEN — Your personal token, available in User settings → Tokens in the NuxtHub Admin
7. Click Add variable

Project Configuration

1. Create a .gitlab-ci.yml in your repository root
2. Paste the following configuration

# if one job fails, pipeline should fail
workflow:
  auto_cancel:
    on_job_failure: all

variables:
  APP_PATH: "PATH/TO/YOUR/APP"
  NUXT_HUB_PROJECT_KEY: "YOUR_NUXT_HUB_PROJECT_KEY"

# add additional steps as needed
stages:
  - deploy
  - callback

deploy_project:
  stage: deploy
  # here we use Bun, you can change this.
  image: "oven/bun:slim"
  script:
    - echo "Deploying project_a app..."
    - cd $APP_PATH
    # you can not use node_modules from cache, since nuxthub needs write access
    - bun install
    # if you set up your variables correctly this should deploy successfully
    - bunx nuxthub deploy
  rules:
    # here we configure auto deploy on branch: staging and main
    - if: '$CI_COMMIT_BRANCH == "staging" || $CI_COMMIT_BRANCH == "main"'

manual_deploy_project:
  stage: deploy
  image: "oven/bun:slim"
  when: manual
  script:
    - echo "Deploying project_a app..."
    - cd $APP_PATH
    - bun install
    - bunx nuxthub deploy

callback:
  stage: callback
  script:
    - echo "Deploy reached."

Monorepo Setup

If you have a monorepo with multiple apps (e.g. ./apps/project-foo), then we make sure our pipelines can run parallel.

1. Create in your repository root a .gitlab-ci.yml
2. Paste the following configuration

# if one job fails, pipeline should fail
workflow:
  auto_cancel:
    on_job_failure: all
stages:
  - trigger_apps

trigger_project_a:
  stage: trigger_apps
  rules:
    - changes:
        - "apps/project-foo/**/*"
  trigger:
    strategy: depend
    include:
      - local: "apps/project-foo/.gitlab-ci.yml"

trigger_project_b:
  stage: trigger_apps
  rules:
    - changes:
        - "apps/project-bar/**/*"
  trigger:
    strategy: depend
    include:
      - local: "apps/project-bar/.gitlab-ci.yml"

add_manual_triggers:
  stage: trigger_apps
  trigger:
    strategy: depend
    include:
      - local: ".manual-triggers.yml"

This configuration separates your main pipeline from child pipelines, each project (app) has its own .gitlab-ci.yml Those child pipelines are only triggered if changes are made in their app folder.

Sometimes GitLab changes are not recognized (previous pipeline failed and new push has no changes in app folder), for that case, you can add manual triggers for the child pipelines by adding a .manual-triggers.yml in the project root.

workflow:
  auto_cancel:
    on_job_failure: all

stages:
  - trigger_apps
  - callback

trigger_project_a:
  stage: trigger_apps
  when: manual
  trigger:
    strategy: depend
    include:
      - local: "apps/project-foo/.gitlab-ci.yml"

trigger_project_b:
  stage: trigger_apps
  when: manual
  trigger:
    strategy: depend
    include:
      - local: "apps/project-bar/.gitlab-ci.yml"

callback:
  stage: callback
  script:
    - echo "manual triggers set"