Skip to content

development.md

Latest commit

 

History

History
178 lines (140 loc) · 7.87 KB

development.md

File metadata and controls

178 lines (140 loc) · 7.87 KB
Raw

Develop and release Slides

Use Node.js 24 or later and pnpm 10. Run commands in this guide from the Slides repository root unless stated otherwise.

Source checkout

git clone https://github.com/allmaps/slides.git
cd slides
pnpm install
git submodule update --init content/slides-template
pnpm exec slides dev ./content/slides-template

The template uses remote images and a Protomaps basemap. Its README explains how to replace the demo API key when copying or forking it. To work on another bundled content repository, initialize its submodule and pass that directory instead. git submodule update --init --recursive initializes all content repositories in a fresh checkout.

For a content repository cloned separately alongside slides, run:

pnpm exec slides dev ../my-story
pnpm exec slides validate ../my-story

To create a new project from this checkout, run pnpm exec slides init ../my-story. The starter pins the checkout's package version. To test unreleased changes as an installed consumer, replace that dependency with a local package archive as described below.

Keep editing the original content files. Markdown and assets reload automatically; configuration edits restart the server. Use a different --port for each server. Refresh generated images with the generation commands.

The root shortcuts pnpm dev, pnpm build, pnpm check, pnpm validate, pnpm iiif and pnpm preview forward to the CLI. Pass the content directory explicitly; initialize it first if it is a submodule:

pnpm dev ./content/slides-template
pnpm check ./content/slides-template
pnpm build ../my-story

Local fixtures can live in the ignored content/tests/; for example, pnpm dev ./content/tests --port 5175.

Generated sites, node_modules/.vite/slides caches and .slides/ development runners are ignored by Git. Add dist/, node_modules/ and .slides/ to the ignore file in a new standalone content repository.

Bundling and packing

pnpm bundle
pnpm test:package
pnpm --filter @allmaps/slides pack --pack-destination ../../artifacts

bundle builds one distributable @allmaps/slides package. It includes the workspace IIIF and renderer code, preprocessed Svelte canvas components, type declarations and application source. The helper packages are private workspace packages; only @allmaps/slides is published. External npm dependencies, including Sharp and Chiitiler, remain runtime dependencies installed by the consumer's package manager.

pack and publish rebuild through the prepack hook. At the repository root, pnpm build <directory> builds a presentation; pnpm bundle builds the npm package. The smoke test packs, installs and exercises a release without publishing it.

The implementation lives in:

Generated import strings are not patched. The packaged renderer runs in a separate Node process; the app's IIIF virtual module contains configuration data, with behavior imported through ordinary server modules.

To try a release archive, run this in a separate content repository, replacing the path with the archive produced by pack:

pnpm add -D /absolute/path/to/allmaps-slides-0.1.0-beta.1.tgz
pnpm exec slides validate .
pnpm exec slides dev .

The current dependency set needs no Zod override. Remove an old zod: 4.4.3 override when upgrading and update the lockfile. Native Linux rendering still needs system dependencies.

Releases

Only @allmaps/slides is published; the bundled app and helpers share its version. Add a changeset for changes to the CLI, app or helpers with pnpm changeset. See publish versions and GitHub releases for the complete process, workflow responsibilities, npm authentication and recovery steps.

Content repositories have their own pinned package dependency and lockfile. They are not workspace packages, so preparing a software release does not need content submodules. Initialize a submodule only when developing that presentation.

Software identity in credits

Packing writes build-info.json inside the package with its version, software commit and source state. The app uses that metadata in the automatic credits footer, and built sites expose it at _app/slides-build.json. A clean packaged build links to the exact GitHub source commit and the matching release notes. The license link opens the repository's LICENSE.md at that commit, or on main for development builds. Packages without a repository URL link to the bundled software notice instead.

Source checkouts show a development label. Uncommitted software changes show a modified label and omit links that would incorrectly identify the base commit as the complete source. Content changes do not affect this status. Builds without usable source metadata show a development label without an exact source link. The metadata never reads a consumer's Git commit, package version or CI variables, and does not contain content paths or repository URLs.

For a fork, set the Slides package's repository.url to its public GitHub repository before committing and packing. A custom application selected with app.directory can provide its matching public source using app.sourceUrl; its source link does not default to the bundled app. See configuration and licensing.

Checks

Every pull request reports the required integration and container checks. Documentation-only changes pass after a quick file check, without installing dependencies or building the container. The shared rules in .github/test-paths.yml exclude guides, software READMEs, changelogs and changeset notes.

Automatic version PRs from this repository's changeset-release/main branch to main also skip expensive tests when a comparison against the PR base confirms that only the Slides package's version field, changelog and Changesets release records changed. Any other manifest field, lockfile, code, configuration, license, workflow or content change runs the full checks. The required checks still report success with a summary explaining the shortcut. Publication keeps its release validation and package build.

Manual workflow runs and PRs exceeding 3,000 changed files always run the full checks; a failed change-detection step fails the required check.

pnpm -r test
pnpm --filter @allmaps/slides check
pnpm --filter @allmaps/iiif check
pnpm --filter @allmaps/static-render check
pnpm --filter @allmaps/svelte-canvas-panel check
pnpm --filter @allmaps/slides test:dev
pnpm --filter @allmaps/slides test:assets
pnpm test:package

The dev smoke runs two independent sites and checks HTTP/WebSocket updates. The asset smoke checks generated overview pages. The package smoke installs a single archive in a fresh content repository and exercises project initialization, type checks, dev, IIIF, native pixels and repeat production builds. It requires registry access and a working native renderer.

Package-specific tests and Docker checks are documented with the renderer, IIIF generator and canvas panel.

Documentation

Keep READMEs focused on purpose, one way to get started and links. Put authoring examples and technical contracts in the documentation index. Content-specific attribution, migration notes and deployment settings belong in that content repository's own docs/ directory so it can be used independently. When changing behavior, update its canonical guide and the template's annotated references rather than repeating the same details across READMEs.