Plugin app data

Where plugins store persistent runtime files and read bundled backend assets. Use AppFolder from @quan-erp/shared-backend-core — never hardcode APP_DATA_FOLDER paths.

Overview

Plugins must keep data and assets in platform-managed folders so paths stay portable across Docker, staging, and production. @quan-erp/shared-backend-core exposes AppFolder helpers that resolve process.env paths for you.

Runtime-generated files → plugin data folder under APP_DATA_FOLDER
Bundled static files → backend/assets (read-only after install)
Temp / partial uploads → APP temp folder (may be cleared)
Never write into the APP_DATA_FOLDER root — always use your plugin subdirectory

1. Application & plugin folders

Four locations matter. Global folders come from env; plugin folders are derived from the plugin name (and version for assets).

Folder	Path	Utility	Use for
App data (global)	process.env.APP_DATA_FOLDER	AppFolder.getAppDataFolder()	Root for all persistent app data — do not write here directly
App temp	process.env.UPLOAD_FILE_TEMP_FOLDER	AppFolder.getAppTempDataFolder()	Temporary files (partial uploads, scratch) — not for durable data
Plugin data	<APP_DATA_FOLDER>/<pluginName>	AppFolder.getPluginDataFolder(pluginName)	Runtime-generated data: exports, reports, local files, caches on disk
Plugin assets	<INSTALLED_PLUGINS_FOLDER>/<pluginName>/<version>/backend/assets	AppFolder.getPluginAssetFolder(pluginName, version)	Read-only static assets shipped with the plugin package

2. Data folder vs asset folder

Use the data folder for anything created or updated while the app runs. Use the asset folder only for files you ship with the plugin source and never mutate at runtime.

Examples for data: generated CSVs, report PDFs, plugin-local SQLite, runtime config files
Examples for assets: document templates, seed JSON, default icons shipped with the backend

	Asset folder	Data folder
Purpose	Static files bundled with the code	Dynamic files created at runtime
Persistence	Replaced when the plugin version is reinstalled / updated	Survives plugin updates
Utility	getPluginAssetFolder(name, version)	getPluginDataFolder(name)
Source in repo	plugins/<name>/backend/assets/	Created on disk at runtime

3. AppFolder API

Import AppFolder from @quan-erp/shared-backend-core. Prefer metadata.name and metadata.pluginVersion so paths stay aligned with module.metadata.json.

Method	Description
getAppDataFolder()	Root application data directory (APP_DATA_FOLDER)
getAppTempDataFolder()	Temporary upload / scratch directory
getPluginDataFolder(pluginName)	Persistent data directory for one plugin
getPluginAssetFolder(pluginName, version)	Installed backend/assets for a plugin version

TSXresolve paths

import { AppFolder } from "@quan-erp/shared-backend-core";
import metadata from "../../module.metadata.json" with { type: "json" };
import fs from "node:fs/promises";
import path from "node:path";

const dataDir = AppFolder.getPluginDataFolder(metadata.name);
const assetDir = AppFolder.getPluginAssetFolder(
  metadata.name,
  metadata.pluginVersion,
);

// Persistent runtime file
await fs.mkdir(dataDir, { recursive: true });
await fs.writeFile(path.join(dataDir, "export.csv"), csv, "utf8");

// Bundled template (read-only)
const template = await fs.readFile(
  path.join(assetDir, "invoice-template.html"),
  "utf8",
);

4. Bundling backend assets

Put static backend files under plugins/<name>/backend/assets/. On build / pack, the CLI copies that tree into the plugin bundle so AppFolder.getPluginAssetFolder can resolve them after install.

Everything under backend/assets/ is packed into available-plugins / installed-plugins
After Install, resolve with getPluginAssetFolder(metadata.name, metadata.pluginVersion)
Do not write into the asset folder at runtime — write to getPluginDataFolder instead

SHsource layout

plugins/<plugin-name>/
└── backend/
    ├── assets/
    │   ├── invoice-template.html
    │   └── seed/
    │       └── defaults.json
    └── src/

Rules

Isolation — only write under getPluginDataFolder(yourPluginName)
Persistence — do not store durable data in getAppTempDataFolder()
Portability — always use AppFolder; never hardcode /app-data/... paths
Versioned assets — pass pluginVersion into getPluginAssetFolder so updates stay isolated