Reference

Package Exports

Bascik ships as a single npm package, @bascik/bascik, with a small set of subpath exports. There is no large SDK surface: the package exposes configuration helpers for your build, a hosting adapter contract for deployment targets, a portable request-execution runtime for serverless hosts, and safe-HTML helpers for your scripts. Everything else is the bascik CLI.

Export map

@bascik/bascik

The main entry resolves to the same module as /config. Most projects only ever import defineConfig from it (or from /config).

import { defineConfig, composeSiteUrl } from "@bascik/bascik";

export default defineConfig({
  base: "/docs/",
});

• defineConfig(config) returns the config unchanged, typed as BascikConfig, so your editor surfaces every option with inline docs.
• composeSiteUrl(siteUrl, base, pathname) joins a site origin, the base path and a page path into an absolute URL (composeSiteUrl("https://example.com", "/docs/", "/about") gives https://example.com/docs/about).

The main entry also exports the types of the scripts Bascik calls:

• BuildScript: the default export of a data-bascik-build or data-bascik-build-once script, which returns a string or an html value (or a promise of either).
• RoutesScript: the default export of a data-bascik-routes script, which returns route objects (RouteEntry).
• ServerScript: the default export of a data-bascik-server or data-bascik-stream script, called with the Request, a ServerScriptContext (remoteIp and platform) and { signal }.

The editor's TypeScript errors in script tags and bascik --check --typescript type a type="text/typescript" script's default export with these, so a script does not import them: a server or stream script imports nothing from @bascik/bascik but @bascik/bascik/html. Use them where code outside a script needs the shape, such as a unit test that calls a handler.

The CLI itself is not importable: run it through the bascik command.

@bascik/bascik/config

The config subpath is the recommended import for bascik.config.ts. It exports defineConfig and re-exports every configuration type, including BascikConfig.

import { defineConfig } from "@bascik/bascik/config";

export default defineConfig({
  generate: { sitemapLastmod: true },
});

@bascik/bascik/runtime

The runtime subpath is the portable request-execution engine that the built-in Node server and every hosting adapter share. It has zero Node builtins, so it bundles cleanly for serverless and edge platforms. Adapter authors use it to serve dynamic pages and API routes from a compiled site graph.

Key functions:

• composeBufferedResponse(plan, run, signal) composes a fully buffered Uint8Array body for a page whose data-bascik-server jobs all resolve before the response starts.
• streamComposedResponse(plan, run, writer, options) drives the two-phase streamer: server jobs resolve before commit, stream jobs run with bounded lookahead after headers are sent. A stream job whose runner resolves to an async iterable (a script that yields) is written one chunk at a time. Returns a ComposedStreamer with ready, commit, done, signal, and toReadableStream().
• invokeWithDeadline(handler, options) runs a handler under a timeout and an upstream AbortSignal, settling exactly once. Once the deadline fires or the upstream aborts, the result is a timeout or an abort even if the handler settles afterwards. invokeLoadedWithDeadline(load, call, options) does the same with a module load under the same deadline, and createAbortGate(signal) is the settlement rule both use. With chunks: true, a handler that returns a generator gives result.source instead of result.value: a ScriptChunkSource pulled one value at a time under the same deadline, which counts only the time a pull is pending. scriptChunkOutput(source, print, fail) turns it into the chunks of a job, and collectScriptJobOutput(output) joins them.
• scriptJobOutput(invoked, policy) turns an invocation's result into the job's output by the rule every host shares: a value is printed, stripped of ANSI escapes and given its component's class names; a value that is not markup is refused; a failure follows scripts.onServerScriptError. settleScriptOutput(result, yielded, policy) is the same for one result. The ScriptOutputPolicy names what is the host's own: its log, its description of a failure, its error class, and how it remembers a script's first refused value. scriptTimeoutError(ms) builds the Script execution timed out after Nms error that server, stream and component scripts report on every host.
• dispatchApiHandler(module, request, context, options) dispatches a web Request to an API route module's exported methods, handling HEAD, OPTIONS, and the Allow header.

The runtime also exports the shared response policy (dynamicPageHeaders, mergeHandlerHeaders, stripRepresentationHeaders, errorResponse, internalErrorPage, SECURITY_HEADERS) and pure route matching (matchApiRoute, sortApiRoutes, pageLookupCandidates, isUnsafePathname, hasHiddenSegment).

@bascik/bascik/adapter

The adapter subpath defines the hosting adapter contract. A custom adapter is a module whose default export is created with defineAdapter; bascik --build --target <name> loads it and calls its build hook with an AdapterBuildContext containing the compiled site graph.

import {
  defineAdapter,
  type AdapterBuildContext,
  type AdapterBuildResult,
} from "@bascik/bascik/adapter";

export default defineAdapter({
  name: "my-cloud",
  async build(context: AdapterBuildContext): Promise<AdapterBuildResult> {
    // Read context.graph, copy context.distDir assets, emit a runtime entrypoint.
    return { publicDir: `${context.outDir}/public` };
  },
});

It also exports the site-graph readers used inside adapters: readSiteGraph, pageAliasesFor, detectPublicCollisions, isPublicAssetPath, and splitDistPageIntoSegments. Importing @bascik/bascik/adapter does not read bascik.config; it loads through CommonJS require or ESM import, and readSiteGraph loads the config on first call.

See Custom Adapters for the full tutorial and API reference.

@bascik/bascik/html

The html subpath is the one export meant for server and stream scripts (build scripts may use it too). It holds plain functions that build HTML safely: the html tagged template, which escapes each value for where it lands and refuses places escaping cannot make safe, plus raw, esc, safeUrl, json, isHtml and HtmlError.

<script data-bascik-server>
  import { html } from "@bascik/bascik/html";

  export default function (request) {
    const q = new URL(request.url).searchParams.get("q") ?? "";
    return html`<p>You searched for ${q}</p>`;
  }
</script>

It has no Node builtins, so the Cloudflare adapter bundles it into the Worker. See HTML Helpers for the API reference and Security for how it fits with the rest of a site's protection.