Routing, Builder & Server

Router

Accessible via pod.router. Manages RouteProvider instances, builds route tables, and resolves URL paths to Route objects.

Method Signature Description
routes routes(): Promise<Route[]> Returns all routes generated by every registered RouteProvider.
resolve resolve(path: string) Resolves a URL path (e.g. '/about/') to its matching Route, or null.
warmup warmup(): Promise<number> Populates the route table and URL maps; returns the total route count.
reset reset(): void Clears cached routes across all providers.
addProvider addProvider(provider: RouteProvider): void Registers a custom RouteProvider subclass.
addRoutes addRoutes(type: string, builder: RouteBuilder) Shortcut to register dynamic routes without subclassing RouteProvider.
addStaticDirectoryRoutes addStaticDirectoryRoutes(configs: StaticDirConfig[]) Registers StaticDirectoryRouteProvider entries from {path, staticDir} mappings.
getUrl getUrl(type: string, item) Looks up the serving Url for a Document ('doc') or StaticFile ('staticDir').

Adding Custom Routes

pod.router.addRoutes('sitemap', async provider => {
  provider.addRoute({
    urlPath: '/sitemap.xml',
    contentType: 'application/xml; charset=utf-8',
    build: async () => '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"></urlset>',
  });
});

RouteProvider, Route, DocumentRoute & StaticRoute

RouteProvider

Base class for route generators (built-in subclasses: DocumentRouteProvider, CollectionRouteProvider, StaticDirectoryRouteProvider).

Member Type / Signature Description
type string Provider category name ('doc', 'staticDir', or custom).
urlMap Map<string, Url> Mapping of item keys to serving Url objects.
routes() Promise<Route[]> Generates and returns routes for this provider.
addRoute(options: RouteOptions) Route Creates and appends a Route ({urlPath, build, contentType?, fields?}).
addRouteBuilder(builder) void Registers an async callback that calls provider.addRoute(...).
reset() void Clears cached routes and urlMap.

Route

Property / Method Type Description
urlPath string Relative serving path (e.g. '/about/').
url Url Full Url object for this route.
podPath string or undefined Source pod path, if backed by a file.
contentType string MIME type inferred from urlPath (trailing / defaults to HTML) or explicit contentType.
fields Record<string, any> Arbitrary metadata attached to the route.
build(options?) Promise<string> Renders and returns the route's string output (options.req passed in dev server).

Builder

Accessible via pod.builder. Compiles routes to static files, writes build manifests (.amagaki/manifest.json), tracks diffs, and exports builds.

Properties & Static Options

Member Default Description
outputDirectoryPodPath '/build' Output directory relative to pod.root.
Builder.NumConcurrentBuilds 10 Concurrency limit for building document routes.
Builder.NumConcurrentCopies 50 Concurrency limit for copying static files.

Methods

Method Signature Description
build build(options?: BuildOptions): Promise<BuildResult> Builds routes (optionally filtered by options.patterns) and optionally writes missing translation catalogs (options.writeLocales).
export export(options: ExportOptions): Promise<BuildDiffPaths> Copies a built directory (buildDir, default 'build') to exportDir, removing stale files using manifest diffs.
getManifest getManifest(filePath: string) Reads an existing BuildManifest JSON file, or returns null.
writeLocales writeLocales(missing): Promise<void> Writes missing translation strings per locale to .amagaki/locales/.

BuildResult

Returned by await pod.builder.build() and passed to afterBuildHook:

Property Type Description
metrics BuildMetrics Contains memoryUsage, numDocumentRoutes, numStaticRoutes, outputSizeDocuments, outputSizeStaticFiles, numMissingTranslations, localesToNumMissingTranslations.
manifest BuildManifest Contains built (ISO timestamp), branch, commit (GitCommit), and files ({path, sha}[]).
diff BuildDiffPaths Lists adds, edits, noChanges, and deletes compared to the previous build manifest.

Server

Express-based development server (amagaki serve) that renders routes on demand and watches files for automatic cache invalidation and amagaki.ts reloads.

import {Pod, Server} from '@amagaki/amagaki';

const pod = new Pod('./my-site', {name: 'default', dev: true});
const server = new Server(pod, {port: 8080});
server.on(Server.Events.LISTENING, ({server}) => {
  console.log(`Listening on http://localhost:${server.port}`);
});
await server.start();
Member Signature / Type Description
port number Active listening port (auto-increments if occupied unless incrementPort: false).
start(options?) Promise<void> Creates the Express app, starts listening, warms up the pod, and starts the file watcher.
stop() Promise<void> Closes the file watcher and stops the HTTP server cleanly.
reload() Promise<void> Evicts module cache, reloads amagaki.ts, and restarts the server.
createApp() Promise<express.Express> Builds the Express app and triggers createServerHook on registered plugins.
clearModuleCache() void Evicts cached Node modules under /plugins and /src.
Server.Events {LISTENING, RELOAD} EventEmitter event names emitted by Server.

Profiler

Accessible via pod.profiler. When enabled (--profile), collects high-resolution timings across builds, routes, and templates and renders summary tables via ProfileReport.

Method Description
pod.profiler.timer(type, label, meta?) Creates a Timer instance (timer.start(), timer.stop()).
pod.profiler.report() Returns a ProfileReport with formatted summary sections (toString()).