Developer Guide

The short version for creating a Lumobase app is to make a Cloudflare deployable app, add a lumobase.jsonc manifest and then package it in a .lumo file. This file can then be shared and installed with anyone on lumobase.co.

Step 1: Setup your app

Lumobase 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 NextJS Guide.

Note that Lumobase does not read any of the settings from your wrangler.jsonc file and instead currently uses some default settings and you define the services your app depends on in lumobase.jsonc (see below). They will be passed to your app similar to how bindings are passed to cloudflare workers.

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).

export default {
  async fetch(request, env, ctx) {
    // env.MAINDB could be a Cloudflare kv namespace
    // if defined in lumobase.jsonc
    return new Response("Hello World")
  }
}

TIP

To run your app locally you can create a wrangler.jsonc file where you define the same bindings as you enter in your lumobase.jsonc file. The settings in the example file below currently corresponds to what is used by Lumobase. Wrangler and the Cloudflare vite plugin requires you to add an id to your bindings, but you can use "-" as a placeholder since those bindings will not be used during local development or by Lumobase anyway.

{
  "name": "my-app",
  "compatibility_date": "2025-05-08",
  "compatibility_flags": ["nodejs_compat"],
  "main": "index.ts",
  "assets": {
    "directory": "public"
  },
  "kv_namespaces": [
    {
      "binding": "MAINDB",
      "id": "-"
    }
  ]
}

Step 2: Add a lumobase.jsonc app manifest

Below is a basic example of a lumobase.jsonc file and it needs to be present in the root of your package. The services defined will be provisioned at install time and passed to your app similar to how bindings are passed to cloudflare workers.

{
  "name": "Snake", // max 30 characters
  "subtitle": "Play the classic of classics", // max 50 characters, shown below the app name
  "icon": "./icon.png", // PNG, preferably 1024x1024 without transparency
  "services": [
    {
      "name": "MAINDB",
      "type": "cloudflare-kv", // Currently the only service type supported is Cloudflare KV and you can only define one per app
    }
  ]
}

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 lumobase.jsonc icon.png public dist/

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

TIP

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

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

Step 4: Share it with the world

Now you can share the .lumo file with the world and anyone can install it on lumobase.co. 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 Lumobase 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://lumobase.co/dash?appUrl={url-to-an-lumo-app}. When a user visits that link it will offer the user to install the app directly. The url should point to a .lumo file. It could for example be a link to a GitHub release asset.