Configuration

Qumra apps use several configuration files to manage environment settings, build tooling, and database access. This guide covers each one in detail.

Environment Variables

Your app reads sensitive credentials and runtime settings from a .env file in the project root.

Variable	Required	Description
QUMRA_API_KEY	Yes	API key from the Qumra Partner Dashboard
QUMRA_API_SECRET	Yes	Secret key from the Qumra Partner Dashboard
DATABASE_URL	Yes	Database connection string (SQLite by default)
QUMRA_APP_URL	No	App URL -- defaults to http://localhost:3000
PORT	No	Server port -- defaults to 3000

.env File Example

.env

# Qumra API credentials (from Partner Dashboard)
QUMRA_API_KEY=qk_live_abc123def456
QUMRA_API_SECRET=qs_live_789ghi012jkl

# Database connection
DATABASE_URL="file:./dev.db"

# Optional overrides
QUMRA_APP_URL=http://localhost:3000
PORT=3000

Never Commit .env to Git

Your .env file contains sensitive API credentials. Make sure it is listed in your .gitignore file (included by default in the scaffold). Never commit secrets to version control.

Qumra Config

The .qumra/qumra.config.json file is auto-generated by the Qumra CLI when you run qumra app init or qumra app dev. It stores metadata about your app's connection to the Qumra platform.

.qumra/qumra.config.json

{
  "appId": "app_abc123",
  "storeId": "store_xyz789",
  "apiVersion": "2025-01",
  "devStore": "my-dev-store"
}

Do Not Edit Manually

The qumra.config.json file is managed by the CLI. Changes made manually may be overwritten the next time you run a CLI command. Use qumra app init or CLI flags to update these values.

Vite Configuration

The vite.config.ts file configures the build tool and dev server. The scaffold includes important settings for iframe development and HMR (Hot Module Replacement).

vite.config.ts

import { reactRouter } from "@react-router/dev/vite";
import { defineConfig } from "vite";
import tsconfigPaths from "vite-tsconfig-paths";

export default defineConfig(({ isSsrBuild }) => ({
  plugins: [reactRouter(), tsconfigPaths()],
  server: {
    hmr: {
      // In development, HMR connects to localhost
      // In production (iframe), this is not used
      host: "localhost",
    },
    cors: {
      // Allow the Qumra admin panel to embed the app
      origin: true,
      credentials: true,
    },
    allowedHosts: true,
  },
  build: {
    rollupOptions: isSsrBuild
      ? {
          input: "./server/app.ts",
        }
      : undefined,
  },
}));

Configuration Breakdown

Setting	Purpose
server.hmr.host	Sets HMR WebSocket to localhost so it works correctly during local development inside an iframe
server.cors	Enables CORS with credentials so the Qumra admin panel can load your app in an iframe
server.allowedHosts	Permits connections from any host, required for the Qumra tunneling during development
build.rollupOptions	Configures the SSR build entry point for production server rendering

Prisma Configuration

Qumra apps use Prisma as the database ORM. The scaffold includes two key Prisma files.

Schema

The prisma/schema.prisma file defines your database schema. The default schema includes a Session model for storing OAuth sessions:

prisma/schema.prisma

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "sqlite"
  url      = env("DATABASE_URL")
}

model Session {
  id          String   @id @default(cuid())
  store       String
  accessToken String
  scopes      String
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt

  @@index([store])
}

Client Initialization

The prisma/lib/prisma.ts file creates a singleton Prisma client to avoid multiple database connections during development:

prisma/lib/prisma.ts

import { PrismaClient } from "@prisma/client";

const globalForPrisma = globalThis as unknown as {
  prisma: PrismaClient | undefined;
};

export const prisma = globalForPrisma.prisma ?? new PrismaClient();

if (process.env.NODE_ENV !== "production") {
  globalForPrisma.prisma = prisma;
}

This singleton pattern prevents Prisma from creating a new database connection on every HMR reload during development.

SQLite for Development, PostgreSQL for Production

The default scaffold uses SQLite (file:./dev.db) for a zero-setup development experience. When deploying to production, switch to PostgreSQL by updating the provider in schema.prisma and the DATABASE_URL in your environment:

.env.production

DATABASE_URL="postgresql://user:password@host:5432/myapp"

prisma/schema.prisma

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

After changing the provider, regenerate the Prisma client with npx prisma generate and create a new migration with npx prisma migrate dev.