Deploy a Nuxt 3 app to Wokku. nuxt build produces a self-contained Nitro
server you run with Node.
Prerequisites
- A Wokku account and a connected server
- An SSH key registered for
git push - A Nuxt 3 app (
npx nuxi init my-appif starting fresh)
1. Create the app
Apps → New App → server, name my-nuxt-app, box size, Create.
bash
wokku apps:create my-nuxt-app --server my-server
2. Prepare your Nuxt app
The Node buildpack runs nuxt build, which outputs .output/. Start the Nitro
server and point it at $PORT:
json
{
"scripts": {
"build": "nuxt build",
"start": "node .output/server/index.mjs"
}
}
procfile
web: npm start
// note
3. Environment variables
App → Config → add NODE_ENV=production plus your runtime config. Public
values (NUXT_PUBLIC_*) are read at runtime by Nitro; private ones stay server-side.
bash
wokku config:set my-nuxt-app NODE_ENV=production
4. Add a database (optional)
bash
wokku addons:create postgres my-nuxt-app
Read process.env.DATABASE_URL in your server routes / ORM. See
Create & Link a Database.
5. Deploy
bash
git remote add wokku git@git.wokku.cloud:my-nuxt-app
git push wokku main
Connect under Apps → Connect GitHub for push-to-deploy —
see GitHub Auto-Deploy.
bash
git remote add wokku git@git.wokku.cloud:my-nuxt-app
git push wokku main
Live at https://my-nuxt-app.wokku.app.
Custom domain
Custom Domains — SSL is automatic.
Troubleshooting
- Crashes on boot — confirm you start
.output/server/index.mjs(notnuxt dev/preview). - Out-of-memory build — pick a larger box size for the build step.