Skip to content
Select theme
Select languageEnglish

Project layout

A project created with acdev new my-app --backend:

my-app/
├── acde.config.jsonc app config: id, name, icon, entry, capabilities
├── package.json
├── index.html entry page
├── src/main.js
├── src/i18n.js picks the language and fills in interface text
├── src/locales/ one message table per language: en.js, zh.js
├── server.ts backend (optional)
├── public/ static files copied as is (optional)
└── .acde/ build output, kept out of git

The html and desktop templates keep interface text out of the markup, in one table per language under src/locales/ (en.js, zh.js, each export default { key: 'text' }). src/i18n.js uses only the platform, no library:

  • locale is chosen from navigator.language: the exact tag if there is a table for it (zh-TW.js), else its base language (zh, via Intl.Locale), else en. A key a table lacks falls back to its English text.
  • t(key, values) returns the text with {name} placeholders filled in.
  • translate() sets <html lang> to locale and fills every element with a data-i18n="key" attribute; index.html ships with lang="en" until then.

To add a language, add src/locales/<tag>.js with the same keys as en.js and import it in i18n.js. Format dates and numbers with Intl and locale (new Intl.DateTimeFormat(locale)). Framework templates keep the UI their own scaffolder writes.

  • acde.config.jsonc is the config you write. It's only read at build time. "type" is "app" (a windowed app) or "desktop" (a desktop).
  • The manifest is the acde field of package.json in the build output, .acde/. That directory is a package: what the runtime runs. The manifest is the only thing the runtime reads.

acdev build turns the former into the latter. Most of the time you only need to care about the config; for the manifest format, see Manifest.

A directory without acde.config.jsonc can still be built:

  • If the acde field in package.json has apps, it's treated as a handwritten package and used as is (only checked).
  • Otherwise it's treated as a default app: the entry is index.html, the id is derived from name in package.json, and the display name comes from displayName or productName.

After building the app my-app:

.acde/
├── package.json manifest
├── web/ web pages, served at /app/my-app/ in the runtime
└── backend/
├── server.js bundled backend
├── package.json {"type": "module"}
└── acde-listen.js preload that turns the backend's listen into a unix socket

A desktop project produces desktop/ (served at /desktop/<id>/), services/<name>.js, and apps/<id>/{web,backend} for the apps it bundles.

Whether a project runs on Bun or Node.js is decided by its package manager: bun → Bun; npm / pnpm / yarn → Node.js. For an existing project, acdev looks at the lockfile, then at the packageManager field in package.json; with neither, the project runs on the runtime acdev itself runs on. acdev new writes packageManager for you.

On Node.js, acdev bundles with the project's own Vite (which is why the built-in templates add vite as a dev dependency under npm / pnpm / yarn); on Bun it uses Bun.build. The bundling rules are the same on both.

The project's dev dependencies include @dopame/acde-api, the SDK that comes with this acdev, by its path on this machine (file:...; the SDK is not on npm, and the project installs where acdev is). acdev new installs it. After upgrading acdev, acdev check and acdev dev say when the project's SDK is older; acdev sdk update brings it to the version this acdev pairs with. It provides:

  • TypeScript types for all acde: modules and the manifest (declarations only: the SDK has no JavaScript)

To reference the types in a JS file:

/// <reference types="@dopame/acde-api/app" />

In a TypeScript project, add "@dopame/acde-api/app" to compilerOptions.types in tsconfig.json. A desktop's pages use @dopame/acde-api/shell instead, which adds the modules only a desktop gets; @dopame/acde-api declares all of them.