Skip to content
Alchemy
GitHubXDiscordRSS

Nuxt

Quick guide to initializing and deploying a Nuxt 3 application to Cloudflare Workers using Alchemy.

This guide shows how to initialize and deploy a Nuxt 3 application to Cloudflare using Alchemy.

Init

Section titled “Init”

Start by creating a new Nuxt project with Alchemy:

Terminal window
bunx alchemy create my-nuxt-app --template=nuxt
cd my-nuxt-app

Login

Section titled “Login”

Authenticate once with your Cloudflare account:

Terminal window
bun alchemy login

Deploy

Section titled “Deploy”

Run the deploy script generated by the template:

Terminal window
bun run deploy

You’ll get the live URL of your Nuxt site:

Terminal window
{
  url: "https://website.<your-account>.workers.dev"
}

Local Development

Section titled “Local Development”

Work locally using the dev script:

Terminal window
bun run dev

Destroy

Section titled “Destroy”

Clean up all Cloudflare resources created by this stack:

Terminal window
bun run destroy

What files are created

Section titled “What files are created”

.env

Section titled “.env”

Alchemy requires a locally set password to encrypt Secrets that are stored in state. Be sure to change this.

ALCHEMY_PASSWORD=change-me

alchemy.run.ts

Section titled “alchemy.run.ts”
/// <reference types="@types/node" />


import alchemy from "alchemy";
import { Nuxt } from "alchemy/cloudflare";


const app = await alchemy("my-nuxt-app");


export const worker = await Nuxt("website");


console.log({
  url: worker.url,
});


await app.finalize();

types/env.d.ts

Section titled “types/env.d.ts”
// Auto-generated Cloudflare binding types.
// @see https://alchemy.run/concepts/bindings/#type-safe-bindings


import type { worker } from "../alchemy.run.ts";


export type CloudflareEnv = typeof worker.Env;


declare global {
  type Env = CloudflareEnv;
}


declare module "cloudflare:workers" {
  namespace Cloudflare {
    export interface Env extends CloudflareEnv {}
  }
}

tsconfig.json

Section titled “tsconfig.json”

The CLI updated the tsconfig.json to include alchemy.run.ts and register @cloudflare/workers-types + types/env.d.ts globally:

{
  "extends": "@nuxtjs/module-builder/tsconfig.json",
  "include": ["**/*", "alchemy.run.ts"],
  "exclude": ["dist"],
  "compilerOptions": {
    "types": ["@cloudflare/workers-types", "./types/env.d.ts"]
  }
}

nuxt.config.ts

Section titled “nuxt.config.ts”

Use the cloudflare-module preset and nitro-cloudflare-dev module to build for Cloudflare in production and development:

import alchemy from "alchemy/cloudflare/nuxt";
import { defineNuxtConfig } from "nuxt/config";


export default defineNuxtConfig({
  devtools: { enabled: true },
  nitro: {
    preset: "cloudflare-module",
    cloudflare: alchemy(),
    prerender: {
      routes: ["/"],
      autoSubfolderIndex: false,
    },
  },
  modules: ["nitro-cloudflare-dev"],
});

If you run nuxt dev without first running Alchemy, you will get an error from nitroCloudflareDev(). This is because Alchemy needs to be run first to create the local environment. We recommend running alchemy dev, which runs nuxt dev automatically.