Developer Guide

The short version for creating a Luvabase app is to make a Cloudflare deployable app, add a luva.jsonc manifest and then package it in a .luva file. This file can then be shared and installed with anyone on luvabase.com.

Step 1: Setup your app

Luvabase apps are deployed to Cloudflare behind the scenes so the easiest way to get started is following one of the official Cloudflare guides such as the Tanstack Start guide.

Note however that Luvabase does not read any of the configuration you set in your wrangler.jsonc file. Instead all configuration for Luvabase is done in the luva.jsonc file (see defaults below).

Public files should be placed in a public directory and if your app has a server side code it should be bundled into a single index.js file (exporting a worker style object with fetch function). If using wrangler you can do this with the --bundle option (see step 3 below).

export default {
  async fetch(request, env, ctx) {
    return new Response("Hello World")
  },
}

::: tip To run your app locally you can use wrangler dev with a wrangler.jsonc file. The options below currently corresponds to what is used by Luvabase.

{
  "name": "my-app",
  "compatibility_date": "2026-01-16",
  "compatibility_flags": ["nodejs_compat"],
  "main": "index.ts",
  "assets": {
    "directory": "public",
  },
}

If your app depend on for example a turso database you can either use a local sqlite file or create your own dev database for local development. :::

Step 2: Add a luva.jsonc app manifest

Below is a basic example of a luva.jsonc file and it needs to be present in the root of your package. The services defined will be provisioned at install time and available as environment variables.

If you for example define that your app uses a turso database (like the below example) a new turso database will be created for each user at install time. Connection strings will then be available on process.env.luva e.g. process.env.luva.maindb.databaseUrl etc

If you add new services later on they will be provisioned when the user installs that update. Services with the same name will not be changed during updates.

{
  "name": "Snake",
  "subtitle": "Play the classic of classics",
  "services": [
    {
      "type": "turso",
      "name": "maindb",
    },
  ],
  "hooks": [
    {
      "type": "install",
      "url": "/api/install",
    },
    {
      "type": "member-update",
      "url": "/api/member-update",
    },
  ],
}

This manifest would mean that something like the below would be available on process.env.luva at runtime.

{
  "version": "",
  "installedAt": "",
  "updatedAt": "",
  "services": {
    "maindb": {
      "type": "turso",
      "databaseUrl": "...",
      "databaseApiToken": "...",
    },
  },
}

If the current user is logged in and has access to the current pod the "x-luva-user-id" and "x-luva-user-name" will also be populated.

Step 3: Package the app

1. Build your app to something that can be deployed directly to Cloudflare. The workers file need to be index.js and public assets need to be in a public directory. Easiest done with wrangler: npx wrangler deploy --dry-run --bundle --outdir dist

2. Copy required files to the new dist folder: cp -r luva.jsonc icon.png public dist/

3. Archive into a .luva file: cd dist && zip -r ../app.luva .

::: tip To make things easier you can add the above steps as a build script in package.json so you can package the Luvabase app with for example npm run build:luva.

{
  ...
  "scripts": {
    "build:luva": "npx wrangler deploy --dry-run --bundle --outdir dist && cp -r luva.jsonc icon.png public dist/ && cd dist && zip -r ../app.luva ."
  }
}

:::

Step 4: Share it with the world

Now you can share the .luva file with the world and anyone can install it on luvabase.com. This can for example be done by adding the app as an asset in a GitHub release. For now users need to update the app manually by uploading a new version by selecting Update from the app options menu.

You can also submit the app to Luvabase to make it among the first to be available in the app store when it launches.

::: tip One way to make your app easier to install for users is adding an install link or button on this format https://luvabase.com/dash?appUrl={url-to-an-luva-app}. When a user visits that link it they can install the app directly. The url should point to a .luva file. It could for example be a link to a GitHub release asset. :::