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). |
DocumentRoute extends Route and exposes doc: Document and locale: Locale.
StaticRoute extends Route and exposes staticFile: StaticFile and servingPath: string.
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()). |