GLofter Theme

中文: README.zh.md

The theme package is an open-source Blocklet-oriented theme development framework for building, previewing, and packaging GLofter-style public-site themes (minimal, magazine, …). Everything you need ships in this repo: a ThemeShell preview UI, mock APIs under api/, and build scripts for distributable theme artifacts—no private Studio tree is required to start from Minimal.

• Public mirror (if forked): https://github.com/shenxiuqiang/glofter-theme

What you get

• Live preview — blocklet dev + Vite client; themes load via getThemeById from src/core/themes.ts.
• Mock public data — theme/api/mock-data/*.json and theme/api/src/routes/mock-theme.ts approximate Studio public endpoints when no upstream Studio URL is configured.
• Per-theme builds — pnpm minimal / pnpm magazine run scripts/build-theme.mjs (output under build/ and packaged zips under package/ per script).
• Blocklet lifecycle — bundle, deploy, upload scripts for the Theme blocklet itself (see package.json).

Requirements

• Node.js 24.
• pnpm (this repo’s root when cloned standalone).

Commands

From the repository root of this project (standalone clone = project root):

pnpm install   # first time or after dependency changes
pnpm dev       # typecheck + blocklet dev: ThemeShell preview + mock API

Lint, per-theme builds, etc. (still from this repo root):

pnpm dev              # same as above: preview + mock API
pnpm lint             # tsc --noEmit + eslint (src + api/src)
pnpm minimal          # build-theme.mjs minimal
pnpm magazine         # build-theme.mjs magazine
pnpm magazine:local   # example: build magazine + copy into local Studio data/themes (machine-specific path in script)
pnpm theme:check      # alias for lint

There is no theme:build script; use minimal / magazine, or extend scripts/build-theme.mjs for new theme ids. Blocklet packaging and release: see bundle, deploy, and upload in package.json.

Repository layout (this package)

Path	Purpose
src/core/themes.ts	Theme registry for preview: themes, getThemeById, default theme.
src/themes/<id>/	Theme source (minimal, magazine, …): index.tsx, pages/, components/, options.schema.json, locale files.
api/mock-data/	JSON fixtures for albums, photographers, services, videos, etc.
api/src/routes/mock-theme.ts	Express routes that serve mock data or proxy to a real Studio when configured.
scripts/build-theme.mjs	Packages a theme id into build/<id>-<version>/ and zip under package/.

Per-theme developer docs:

• Minimal — README.md (English, default) · README.zh.md (中文)
• Magazine — README.md (English guide) · README.zh.md (中文)

Registering a new theme

1. This package — Add the theme module under src/themes/<your-id>/, export a ThemeDefinition, then register it in src/core/themes.ts.
2. Host app (optional) — If you ship the theme into GLofter Studio or another host that keeps its own registry, register the same ThemeDefinition there (in the full GLofter monorepo that is typically studio/src/themes/index.ts). Open-source contributors working only in this repo do not need a studio/ tree.

Details: when this folder sits inside the GLofter monorepo, see docs/tech/theme-system.md and docs/tech/themes/system.md. In a standalone clone, read the same files in the main GLofter repository.

Start a new theme from Minimal

src/themes/minimal in this repository is the reference implementation and the recommended base. Copy it to a new id and iterate—no access to any private studio/ path is required.

Example (from this repo root):

cp -R src/themes/minimal src/themes/my-theme
# Then replace id/displayName in src/themes/my-theme/index.tsx,
# register in src/core/themes.ts, and adjust options.schema.json / pages as needed.

pnpm lint

Keep minimal itself as the shared reference; fork under a new directory name so upgrades and diffs stay easy to follow.

Where installed themes live (GLofter Studio)

When a GLofter Studio instance installs a theme from the marketplace or a zip, unpacked files are usually served from a per-id version directory on disk (often data/themes/<id>/<version>/ under that Studio’s data root). That tree is typically gitignored and is runtime content, not part of this theme framework source.

Security

Theme ZIP distribution expects author signing + Hub secondary signature. Do not weaken CSP or validation to “make previews work” in production.

Documentation

Paths below assume this package lives next to docs/ in the GLofter monorepo. In a standalone glofter-theme clone, open the same relative paths in the main GLofter repository.

• Theme system (technical)
• Themes — system details
• Preview flow
• Themes — product overview
• Theme status flow
• Theme system todo / roadmap

License

Code is licensed under the MIT License.