dbpen.io

Online code editor and database browser powered by HoloDB and Next.js.

Development

npm run dev

By default, saved configurations are written below .dbpen-data/ in the current working directory. Override it with:

DBPEN_DATA_DIR=/absolute/path/to/dbpen-data npm run dev

Initial YAML

The landing page prerenders the configured initial YAML together with a static, syntax-highlighted editor preview. CodeMirror hydrates over that preview on the client.

Default mode:

npm run build

Prerender the sample YAML explicitly:

npm run build --dbpen-initial-yaml=sample

Prerender an empty editor:

npm run build --dbpen-initial-yaml=empty

Equivalent explicit empty override:

npm run build --dbpen-initial-yaml-empty

Read initial YAML from a file:

npm run build --dbpen-initial-yaml-file=./sample.yaml

The same options can be supplied as environment variables:

• DBPEN_INITIAL_YAML_MODE=sample|empty
• DBPEN_INITIAL_YAML=sample|empty
• DBPEN_INITIAL_YAML_EMPTY=true
• DBPEN_INITIAL_YAML_FILE=./sample.yaml

URL State

• / starts with demo content.
• /edit starts with an empty editor.
• /d/<id> starts with backend-provided saved content when it exists, otherwise with an empty editor so local recovery can run in the browser.

Client-side URL changes use history.replaceState() so editor and layout state are not remounted. Unsaved editor content is canonicalized to /edit; a successful save is canonicalized to /d/<id>.

Offline Support

Saved YAML records are cached in local storage under dbpen.saved-yaml.v1. Remote saves update this cache with localOnly: false and a real expiration. When offline, Save asks for confirmation and writes a localOnly: true record with expiresAtEpochSeconds: -1. Expired online-backed local records are reported during writes, but not deleted yet.

If /d/<id> loads empty content, the client treats that as a backend not-found signal. It checks for a local record with the same ID, offers local recovery if one exists, or reports that the configuration was not found. Hash-loaded YAML is integrity-checked against the route ID before it is accepted as saved.

The service worker is served from /sw.js. It is registered automatically in production builds, and in development only when explicitly enabled:

NEXT_PUBLIC_DBPEN_ENABLE_SW=true npm run dev

The worker caches the app shell and static assets, falls back to the cached shell for offline navigations, and accepts messages from the app to cache saved /d/<id> route shells after successful saves.

Async Content Replacement

Client components under EditorStateProvider can call replaceEditorContent(value) from useEditorState(). The editor applies the replacement safely whether CodeMirror has already mounted or is still loading, then evaluates the same YAML state used by the rest of the UI.

Backend API

The frontend saves by posting raw YAML to /api/d.

• POST /api/d
  • request body: YAML
  • request content type: application/yaml; charset=utf-8
  • success status: 201 Created
  • response body: empty
• GET /api/d/<hash-id>
  • success status: 200 OK
  • response body: YAML
  • response content type: application/yaml; charset=utf-8

Both endpoints return metadata in headers:

• X-DBPen-Id
• X-DBPen-Created-At
• X-DBPen-Expires-At

Saved records are content-addressed with SHA-256 over the UTF-8 YAML bytes. Storage layout:

<data-dir>/
  <hash-id>/
    config.yaml
    metadata.yaml
    preview.html

preview.html is derived from config.yaml at save time and is used for the initial editor preview on saved pages. The page still works if it is missing, but the editor can briefly fall back to the client-side activation path. The default TTL is one day. Override it with DBPEN_SAVE_TTL_SECONDS.

Next Backend Deploy

Use this when generic Node/Next hosting is available:

pnpm build
DBPEN_DATA_DIR=/absolute/path/to/dbpen-data pnpm start

The Next backend serves:

• the application pages,
• POST /api/d,
• GET /api/d/<hash-id>,
• SSR initial content for /d/<hash-id>.

For a container-ready standalone artifact, use:

pnpm dist:next

This creates:

• build/next/
• build/dbpen-next.tar.gz

Run the standalone build with:

cd build/next/app
DBPEN_DATA_DIR=../data node server.js

The standalone artifact uses a private-root layout:

build/next/
  app/
  data/

PHP Backend Deploy

Use this for restricted classical PHP hosting.

Build the PHP/static deployable artifact:

pnpm dist:php

This creates:

• build/php/
• build/dbpen-php.tar.gz

Deploy by copying build/php/ to the host and configuring build/php/public/ as the document root.

The PHP artifact uses a private-root layout:

build/php/
  public/
  app/
  data/

Make data/ writable:

chmod 775 build/php/data

By default the PHP backend uses ../data relative to public/. If the hosting panel supports environment variables, set DBPEN_DATA_DIR to an absolute writable directory instead.

The PHP backend serves:

• /, /edit, /d/<hash-id> through index.php,
• POST /api/d through api/d.php,
• GET /api/d/<hash-id> through api/d.php.

For /d/<hash-id>, PHP serves the exported empty editor page and injects the saved YAML into window.__DBPEN_RUNTIME_INITIAL_CONFIG__ before hydration. If the saved record has preview.html, PHP also injects that preview into the editor preview slot before the response is sent.

Production Artifacts

Next.js still writes its own framework-native outputs:

• .next/ for normal Node/Next builds,
• out/ for static export builds.

Those are intermediate framework outputs. The stable deployable artifacts are assembled under build/:

pnpm dist:next
pnpm dist:php
pnpm dist