Deploy Nuxt on the Edge

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.

DeploymentsDeployment Details

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

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

GitHub Action

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
    environment:
      name: ${{ github.ref == 'refs/heads/main' && 'production' || 'preview' }}
      url: ${{ steps.deploy.outputs.deployment-url }}
    permissions:
      contents: read
      id-token: write

    steps:
      - uses: actions/checkout@v4

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

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

      - name: Install dependencies
        run: pnpm install

      - name: Build application
        run: pnpm run build

      - name: Deploy to NuxtHub
        uses: nuxt-hub/action@v1
        id: deploy

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

NuxtHub automatically copies all your project's environment variables to your GitHub repository actions environment variables.

When encrypting an environment variable in the NuxtHub Admin, a GitHub actions secret will be created in your repository.

In order to use GitHub Actions secret, you need to update the GitHub Actions workflow to use the secret as environment variable:

  - name: Build application
    run: pnpm run build
+   env:
+     NUXT_UI_PRO_LICENSE: ${{ secrets.NUXT_UI_PRO_LICENSE }}

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.

Cloudflare Pages CI

Importing an existing Cloudflare Pages project that is already linked to a Git repository will use Cloudflare Pages CI to deploy your project.

• Each commit will trigger a new deployment within Pages CI.
• Environment variables set within NuxtHub Admin will be available during CI.

Self-hosted

You can deploy your project on your own Cloudflare account without using the NuxtHub Admin.

For that, you need to create the necessary resources in your Cloudflare account and configure your project to use them (D1, KV, R2, etc.).

Then, create a Cloudflare Pages project and link your GitHub or Gitlab repository and choose the Nuxt Framework preset in the build settings.

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

• Runtime > Compatibility flags
  • Add the nodejs_compat flag
• 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
  • AI: AI
  • Browser: BROWSER
  • Vectorize: VECTORIZE_<index name in upper case> and select your Vectorize index created
    

    # Create the Vectorize index manually using
    npx wrangler vectorize create <index-name> --dimensions=<dimensions> --metric=<metric>
    

Go back to the Deployment tab and retry the last deployment by clicking on ... then Retry deployment.