settings

layout	docs
docsOrder	70
handlebars	false

Settings

Use settings modules to define site-wide variables and customize DOMStack's JavaScript, CSS, and Markdown build tools. These files can live anywhere under src; they configure the build and are not emitted as browser assets. For shared scripts and styles, see Global bundles.

Only one file may match each global filename pattern. When DOMStack discovers a duplicate, it keeps the first file it found, skips the duplicate, and reports a warning. Define each global file once rather than relying on discovery order.

Wherever this page uses .ts, you can also use .js. See Supported file types for all available extensions.

Table of Contents

[[toc]]

global.vars.ts

The global.vars.ts file should default-export a variable provider. The variables in this file are available to all pages, unless the page sets a variable with the same key, taking a higher precedence. These defaults are separate from the computed, explicitly subscribed values described in Data.

export default {
  siteName: 'The name of my website',
  authorName: 'Mr. Wallace'
}

browser variable

global.vars.ts can uniquely export a variable provider named browser. These variables are made available in all client bundles.

export const browser = {
  'process.env.TRANSPORT': 'http',
  'process.env.HOST': 'localhost'
}

The exported object is passed to esbuild's define options and is available to every js bundle. Domstack also reserves process.env.DOMSTACK_MANIFEST_URL, process.env.DOMSTACK_MANIFEST_VERSION, process.env.DOMSTACK_MANIFEST_ENABLED, process.env.DOMSTACK_SERVICE_WORKER_URL, and process.env.DOMSTACK_SERVICE_WORKER_SCOPE for generated build facts.

Warning

Setting define in esbuild.settings.ts while also using the browser export will throw an error. Use one or the other.

esbuild.settings.ts

This is an optional file you can create anywhere. It should export a default sync or async function that accepts a single argument (the esbuild settings object generated by domstack) and returns a modified build object. Use this to customize the esbuild settings directly.

Important esbuild settings you may want to set here are:

• target - Set the target to make esbuild run a few small transforms on your CSS and JS code.
• jsx - Configure how esbuild transforms JSX and TSX.
• jsxImportSource - Set this when using an automatic JSX runtime such as React or Preact.
• define - Define compile-time constants for JS bundles. Setting define here conflicts with the browser export in global.vars.ts and throws an error if both are set.

Warning

An invalid esbuild override can break DOMStack's browser build. Preserve DOMStack's required build options unless you intentionally replace their behavior.

Here is an example of using this file to polyfill Node.js built-ins in the browser bundle:

import { polyfillNode } from 'esbuild-plugin-polyfill-node'
// BuildOptions re-exported from esbuild
import type { BuildOptions } from '@domstack/static/types.js'

const esbuildSettingsOverride = async (esbuildSettings: BuildOptions): Promise<BuildOptions> => {
  esbuildSettings.plugins = [polyfillNode()]
  return esbuildSettings
}

export default esbuildSettingsOverride

Default build behavior

DOMStack passes its complete default BuildOptions into this function. The default browser build:

• Bundles ESM with code splitting enabled
• Emits source maps and an esbuild metafile
• Preserves source-relative directories through outbase: src
• Uses [dir]/[name]-[hash] for production entry files and stable [dir]/[name] filenames in watch mode
• Writes shared chunks to chunks/[ext]/[name]-[hash]
• Does not configure a JSX runtime

Default asset loaders are:

Loader	Extensions	Behavior
dataurl	.png, .jpg, .jpeg, .gif, .svg, .webp, .avif	Embeds the imported asset in its bundle
file	.ico, .woff, .woff2, .ttf, .eot, .otf	Emits a separate file and returns its URL

Note

Images imported by a client bundle are embedded regardless of their size by default. Use the file loader when large images should remain separate files.

The function's return value becomes the effective esbuild configuration. Preserve DOMStack's build wiring, including entryPoints, outdir, and outbase, unless you intentionally replace that behavior. Spread nested options such as loader when adding entries because replacing the object discards its existing defaults. DOMStack preserves its reserved define values after the override runs.

These options also form the basis of the service-worker build. DOMStack replaces the service-worker entry point and filename and disables code splitting, while options such as plugins, loaders, target, and JSX configuration carry over.

You can return a shallow copy that modifies the defaults when you only need a small change. For example, this keeps DOMStack's default asset loaders and adds a custom loader for .wasm files:

import type { BuildOptions } from '@domstack/static/types.js'

const esbuildSettingsOverride = async (esbuildSettings: BuildOptions): Promise<BuildOptions> => {
  return {
    ...esbuildSettings,
    loader: {
      ...esbuildSettings.loader,
      '.wasm': 'file',
    },
  }
}

export default esbuildSettingsOverride

If you want full control, reset DOMStack's convenience defaults back to esbuild's defaults while preserving the required DOMStack build wiring (entryPoints, outdir, outbase, etc.). From there, define only the settings you want:

import type { BuildOptions } from '@domstack/static/types.js'

const esbuildSettingsOverride = async (esbuildSettings: BuildOptions): Promise<BuildOptions> => {
  return {
    ...esbuildSettings,
    jsx: undefined,
    jsxImportSource: undefined,
    loader: {
      '.png': 'file',
      '.svg': 'text',
    },
  }
}

export default esbuildSettingsOverride

markdown-it.settings.ts

This is an optional file you can create anywhere. It should export a default sync or async function that accepts a single argument (the markdown-it instance configured by domstack) and returns a modified markdown-it instance. Use this to add custom markdown-it plugins or modify the parser configuration. Here are some examples:

import markdownItContainer from 'markdown-it-container'
import markdownItPlantuml from 'markdown-it-plantuml'
import type { MarkdownIt } from 'markdown-it'

const markdownItSettingsOverride = async (md: MarkdownIt) => {
  // Add custom plugins
  md.use(markdownItContainer, 'spoiler', {
    validate: (params: string) => {
      return params.trim().match(/^spoiler\s+(.*)$/) !== null
    },
    render: (tokens: any[], idx: number) => {
      const m = tokens[idx].info.trim().match(/^spoiler\s+(.*)$/)
      if (tokens[idx].nesting === 1) {
        return '<details><summary>' + md.utils.escapeHtml(m[1]) + '</summary>\n'
      } else {
        return '</details>\n'
      }
    }
  })

  md.use(markdownItPlantuml)

  return md
}

export default markdownItSettingsOverride

import markdownIt, { MarkdownIt } from 'markdown-it'
import myCustomPlugin from './my-custom-plugin'

const markdownItSettingsOverride = async (md: MarkdownIt) => {
  // Create a new instance with different settings
  const newMd = markdownIt({
    html: false,        // Disable HTML tags in source
    breaks: true,       // Convert \n to <br>
    linkify: false,     // Disable auto-linking
  })

  // Add only the plugins you want
  newMd.use(myCustomPlugin)

  return newMd
}

export default markdownItSettingsOverride

By default, DOMStack ships with the following markdown-it plugins enabled:

• markdown-it
• markdown-it-footnote
• markdown-it-highlightjs
• markdown-it-emoji
• markdown-it-sub
• markdown-it-sup
• markdown-it-deflist
• markdown-it-ins
• markdown-it-mark
• markdown-it-abbr
• markdown-it-task-lists
• markdown-it-github-alerts
• markdown-it-anchor
• markdown-it-attrs
• markdown-it-table-of-contents