Config

Every table on this page is generated from the library on each build: keys, types, defaults and descriptions from src/config/types.ts and src/tty/types.ts, and the mode each key works in from the validator itself. The guides show these keys in use; start with Web apps or Terminal apps.

A config file (showcase.config.ts, .mts, .mjs or .js) exports its config as the default export, usually through defineConfig, which only adds type checking and editor completion:

showcase.config.mjs

import { defineConfig } from '@noctcore/showcase-kit';

export default defineConfig({
  name: 'My App',
  target: { mode: 'url', url: 'http://localhost:5173', start: 'pnpm dev' },
  shots: [{ id: 'home', title: 'Home', nav: '/' }],
});

target.mode decides the kind of config. 'url' and 'cdp' capture a web page (web in the tables below); 'tty' runs a terminal app (tty). A key marked web only or tty only works in that kind alone; an unmarked key works in both.

Validation

The config is checked before anything runs, and every problem is reported at once, each with its path, so one run shows the whole list:

Invalid showcase config (showcase.config.mjs):
  - config.viewPort: unknown key (expected one of: name, slug, root, target, ready, viewport, ...)
  - shots[1].id: duplicates another shot id "home"
  - frame.padding: must be an integer >= 0, got "72"

• Unknown keys are errors, so a typo such as viewPort is not silently ignored. The message lists the keys that object accepts (config stands for the top level).
• A key of the other mode gets its own message, such as config.viewport: not used in tty mode (the image size comes from ...). The full list is in Keys in the wrong mode.
• Relative paths resolve against the config file’s directory, or against root when you set it (root itself is relative to the config file’s directory). That covers the outputs paths, outputs.portfolio.dir and gallery, target.cwd, hero.logo and the terminal.font files.
• Path templates only take the tokens listed in Path templates, and must contain the ones that keep files apart.

From code, resolveConfig(object, rootDir) runs the same checks on a config object: see the programmatic API.

Top level

Key	Type	Default	Meaning
name	string	required	App name, used in frame titles and alt text.
slug	string	the name, lowercased, with dashes for everything else	Used for the {slug} token. Letters, digits, - and _.
root	string	the config file's directory	Base directory for relative paths, itself relative to the config file's directory.
deviceScaleFactor	number	2	Device pixels per CSS pixel, 0.25 to 4: every image is this many times its CSS pixel size.
langs	string[]	['en']	Languages to capture, in order. Each gets its own setup run.
frame	FrameOptions	per key	The window frame around the README images. Portfolio images, the hero and clips use the same look.
outputs	Outputs	per key	Where the files go.
hero	HeroOptions	per key	Banner image for the top of a README: logo, name, tagline and framed shots, in one of several layouts.
browser	BrowserOptions	per key	The Chromium that captures web apps, renders terminal screens and draws frames.
timeouts	Timeouts	per key	How long to wait for the app and for each shot.
targetweb only	WebTarget	required	How to reach the app: mode: 'url' or mode: 'cdp'.
targettty only	TtyTarget	required	How to run the app: mode: 'tty'.
readyweb only	string	none	Selector that exists once the app has booted.
readytty only	string | RegExp	none	Text on screen once the app has drawn: a substring or a RegExp.
viewportweb only	{ ... }	{ width: 1440, height: 900 }	CSS pixel size of every capture.
colorSchemeweb only	'light' | 'dark' | 'no-preference'	'dark'	The prefers-color-scheme the page sees.
cssweb only	string	none	Extra CSS injected before each shot, for example to hide dev overlays.
setupweb only	(ctx: SetupContext) => Promise<void> | void	none	Runs once per language after the app is ready: seed fixtures, switch locale, dismiss dialogs.
setuptty only	(ctx: TtySetupContext) => Promise<void> | void	none	Runs in each new app process once it is ready, before its first shot or clip.
shotsweb only	Shot[]	required	The views to capture, in order.
shotstty only	TtyShot[]	required	The screens to capture, in order, in one app process per language.
terminaltty only	TerminalOptions	per key	How the terminal looks: theme, font, line height, padding, cursor.
clipstty only	Clip[]	per key	Animated recordings, written by showcase record (and showcase all).

viewport

Key	Type	Default	Meaning
width	number	required	Width in CSS pixels, 16 to 8192.
height	number	required	Height in CSS pixels, 16 to 8192.

browser

Which Chromium the kit launches, and how.

Key	Type	Default	Meaning
channel	string	none	A Playwright channel such as chrome or msedge, to use an installed browser instead of a downloaded one.
executablePath	string	none	Path to a Chromium based browser to launch instead of the downloaded Chromium.
headless	boolean	true	Run the browser without a window.
args	string[]	none	Extra command line arguments for the browser.

timeouts

How long to wait, in milliseconds.

Key	Type	Default	Meaning
readyMsweb only	number	30000	Wait for the ready selector, in milliseconds. Not used in tty mode (see target.readyTimeoutMs).
shotMs	number	15000	Navigation and waitFor per shot, in milliseconds. In tty mode it bounds each waitFor and clip waitFor step.
networkIdleMsweb only	number	3000	Best-effort network idle wait, in milliseconds; a busy dev server only costs this much. Not used in tty mode.

target

How the kit reaches the app. The mode picks one of three shapes.

target in url mode

A web app the kit opens in its own headless Chromium, starting it first if needed.

Key	Type	Default	Meaning
mode	'url'	required	Capture the app in the kit's own headless Chromium.
url	string	required	The app's URL. nav paths that start with / resolve under its path: it is the app's base directory.
start	string	none	Shell command that starts the app (for example pnpm dev:web). Omit if it is already running.
cwd	string	the config root	Working directory for start, relative to the config root.
env	Record<string, string>	none	Extra environment for start.
readyTimeoutMs	number	60000	How long to wait for url to answer after start, in milliseconds.
reuseExisting	boolean	true	Use an app that already answers on url instead of starting a second copy.

target in cdp mode

A running Chromium based app the kit attaches to over the DevTools Protocol.

Key	Type	Default	Meaning
mode	'cdp'	required	Attach to a running Chromium based app (Electron, or WebView2 on Windows) over the DevTools Protocol.
cdpUrl	string	'http://127.0.0.1:9222'	The app's remote debugging endpoint.
pageMatch	string | RegExp	the first page that is not a devtools page	Picks the page to capture: a substring of its URL, or a RegExp.
start	string	none	Shell command that launches the app with remote debugging on. Omit if it is already running.
cwd	string	the config root	Working directory for start, relative to the config root.
env	Record<string, string>	none	Extra environment for start.
readyTimeoutMs	number	60000	How long to wait for the CDP endpoint to answer after start, in milliseconds.

target in tty mode

Runs a terminal app in a pseudo terminal and captures its screen. Needs @lydell/node-pty (or node-pty).

Key	Type	Default	Meaning
mode	'tty'	required	Run a terminal app in a pseudo terminal.
command	string | [file: string, ...args: string[]]	required	Command to run: a string goes through the shell like start; an array [file, ...args] is spawned directly.
cwd	string	the config root	Working directory, relative to the config root.
env	Record<string, string> | ((ctx: { lang: string }) => Record<string, string>)	none	Extra environment. A function gets the language, for apps that take their locale from an env var.
inheritEnv	boolean | string[]	true	Which of your environment variables the app inherits. true: all but CI and terminal hints. false or []: only what the platform needs to start a program (PATH; on Windows also PATHEXT, SystemRoot, ComSpec). An array of names: those as well.
cols	number	120	Terminal width in columns, 10 to 500.
rows	number	32	Terminal height in rows, 5 to 200.
quitKey	string | false	'q'	Key sent to quit before the process tree is killed, parsed like keys. false just kills.
inputDelayMs	number	300	Grace after ready, before setup and the first key, for apps that enter raw mode after drawing, in milliseconds.
readyTimeoutMs	number	30000	How long to wait for the ready text, in milliseconds.

shots

The views (or terminal screens) to capture, in order. Web and tty shots share most keys; the rest are marked web only or tty only.

Key	Type	Default	Meaning
id	string	required	File name stem and {id} token. Letters, digits, - and _.
title	string	the shot's id	Human name, used in frame titles and gallery alt text.
caption	string	the shot's title	Caption under the image in the README table and the portfolio gallery.
alt	string	the app name and the title, as <name>: <title>	Alt text.
navweb only	Nav	per key	How to reach the view: a selector to click, a path or URL to visit, { click }, { goto } or your own steps.
navtty only	TtyNavFn = (tty: TtySession) => Promise<void> | void	none	Or your own steps with the session. Use keys or nav, not both.
waitForweb only	string	none	Selector to wait for, until it is visible, after navigating.
waitFortty only	string | RegExp	none	Text on screen to wait for after the keys: a substring or a RegExp.
delayMsweb only	number	0	Extra settle time after navigating, in milliseconds.
delayMstty only	number	0	Extra settle time after waitFor, in milliseconds.
keystty only	Keys = string | string[]	none	Keys to press: plain text is typed, names in braces are keys ({Tab}, {Down}, {Enter}, {C-c}).
restarttty only	boolean	false	Start a fresh app process (and run setup again) before this shot.

shots[].nav

How to reach a shot.

• A string starting with / (but not //) or http(s):// is visited as a URL. In url mode a path resolves under the target URL's path (/docs/ with https://x.io/app/ visits https://x.io/app/docs/); in cdp mode it resolves against the captured page's origin.
• Any other string is a selector to click.
• { click } and { goto } say which one explicitly.
• A function receives the page and does whatever it needs.

Form	Meaning
string	A selector to click, or a path or URL to visit, told apart as above.
{ click: string }	A selector to click.
{ goto: string }	A path or URL to visit.
NavFn	Your own steps with the page.

frame

How a capture is framed for the README, the portfolio, the hero and clips.

Key	Type	Default	Meaning
style	FrameStyle = 'window' | 'minimal' | 'none' | 'browser' | 'windows' | 'terminal'	'window'	window: title bar with traffic lights. minimal: thin bar. none: just the rounded screenshot. browser: a browser toolbar with the address in its address bar (url and cdp mode). windows: a Windows title bar, the title on the left and the caption buttons on the right. terminal: a terminal emulator's bar, a tab with the title in a monospace font; in tty mode it takes the terminal's background, so bar and screen read as one.
theme	'light' | 'dark'	'dark'	Title bar colors.
title	string | false	'{name}'	Title bar text. Tokens: {name}, {title}, {id}, {lang}. false hides it.
address	string	'{url}'	Address bar text for style: 'browser'. Tokens: {url}, {name}, {title}, {id}, {lang}. {url} is the page the shot visits without http:// or https://: the target url, resolved with the shot's nav when that is a path or URL. In cdp mode the page is not known when framing, so write the text without {url}.
background	Background	{ type: 'gradient', from: '#0f766e', to: '#1e1b4b', angle: 135 }	What the window sits on.
padding	number	72	Space around the window, in CSS pixels.
radius	number	14	Window corner radius, in CSS pixels.
shadow	boolean	true	Soft drop shadow under the window.
quality	number	90	WebP quality, 1 to 100.
maxWidth	number	none	Downscale README images wider than this many pixels.

frame.background

What a frame or the hero sits on.

Form	Meaning
string	A CSS color, the same as { type: 'solid', color }.
{ type: 'solid'; color: string }	One CSS color.
{ type: 'gradient'; from: string; to: string; angle?: number }	A linear gradient between two CSS colors. angle (optional): Angle in degrees, -360 to 360. Default: 135.
{ type: 'transparent' }	No background: the space around the window stays transparent.
{ type: 'mesh'; colors: string[] }	A mesh gradient: the first color underneath, each other color glowing from its own corner. colors: Two to five CSS colors: the base, then the top left, top right, bottom right and bottom left glows.
{ type: 'dots'; color: string; dot?: string; spacing?: number }	A subtle grid of dots on one CSS color. color: The color under the dots. dot (optional): The dot color. Pick a dark one on a light color. Default: 'rgba(255,255,255,0.14)'. spacing (optional): Distance between dots in CSS pixels, 8 to 96. Default: 24.
{ type: 'noise'; from: string; to: string; angle?: number; amount?: number }	A linear gradient with a film grain on top, the same on every run. angle (optional): Angle in degrees, -360 to 360. Default: 135. amount (optional): How strong the grain is, 0 to 1. Default: 0.2.

outputs

Where each kind of file is written, relative to the config root.

Key	Type	Default	Meaning
raw	string	'showcase-out/raw/{lang}/{id}.png'	Raw capture path (PNG). Tokens: {lang}, {id}, {slug}.
readme	string | false	'assets/showcase/{lang}/{id}.webp'	Framed README image path (.webp or .png). Tokens: {lang}, {id}, {slug}. false skips the README images, for configs that only export a portfolio (which renders from the raw captures).
portfolio	PortfolioOutput	per key	Portfolio export: fixed-size images, a thumbnail and a gallery JSON. Off unless set.
clipstty only	string	'assets/showcase/{lang}/{id}.{ext}'	Clip path, ending in .{ext}. Tokens: {lang}, {id}, {slug}, {ext}.

outputs.portfolio

Fixed-size images for a portfolio site, a thumbnail and a gallery JSON.

Key	Type	Default	Meaning
dir	string	required	Output directory. Token: {slug}.
size	[number, number]	[1920, 1080]	Exact output size in pixels, 16 to 8192 a side.
format	'webp' | 'png'	'webp'	Image format.
quality	number	90	WebP quality, 1 to 100.
thumbnail	string	the first shot	Shot id copied to thumbnail.<format>.
lang	string	the first of langs	Which language to export.
publicPath	string	'/projects/{slug}'	URL prefix used for src in showcase.gallery.json. Token: {slug}.
padding	number	96	Minimum space around the window, in output pixels.
gallery	string | false	showcase.gallery.json in dir	Where to write the gallery JSON, relative to the config root (token {slug}, must end in .json), or false to skip it.

hero

The README banner that showcase hero renders.

Key	Type	Default	Meaning
layout	HeroLayout = 'stack' | 'spotlight' | 'split' | 'row' | 'mosaic' | 'centered'	'stack'	How the banner is composed: stack, spotlight, split, row, mosaic or centered.
tagline	string	none	Line under the name.
logo	string	none	Logo image (PNG, SVG, WebP or JPEG), relative to the config root.
shots	string[]	as many of the first shots as the layout shows	Shot ids to show, back to front: one to three for stack, one to four for row and mosaic, one for the others.
lang	string	the first of langs	Which language's captures to use.
output	string	'assets/showcase/hero.webp'	Output path (.webp or .png). Tokens: {lang}, {slug}.
size	[number, number]	[1280, 640]	Exact output size in pixels, 320 to 8192 a side. The default is the GitHub social preview size.
background	Background	the frame's background	What the banner sits on, in the same forms as frame.background.
theme	'light' | 'dark'	the frame's theme	Text color scheme: 'dark' draws light text, 'light' dark text.
quality	number	90	WebP quality, 1 to 100.

terminal

How the terminal looks when rendered. Every field is optional in config.

Key	Type	Default	Meaning
theme	'dark' | 'light' | TerminalTheme	'dark'	Colors: 'dark' (Tokyo Night), 'light' (Tokyo Night Day) or your own palette.
font	{ ... }	per key	Font files and size.
lineHeight	number	1.32	Line height as a multiple of the font size (1 to 3), rounded to whole pixels.
padding	number	12	CSS pixels between the grid and the edge of the capture, 0 to 400.
cursor	'hide' | 'show'	'hide'	Whether to draw the cursor. A shown cursor never blinks.

terminal.theme

A custom palette instead of 'dark' or 'light':

A 16 color ANSI palette plus the default colors.

Key	Type	Default	Meaning
background	string	required	Background color, #rrggbb.
foreground	string	required	Default text color, #rrggbb.
cursor	string	the foreground color	Cursor color, #rrggbb.
ansi	string[]	required	Exactly 16 colors: the 8 normal ANSI colors, then the 8 bright ones.

terminal.font

Key	Type	Default	Meaning
file	string	the bundled JetBrains Mono	Font file (woff2, woff, ttf or otf), relative to the config root.
boldFile	string	the bundled JetBrains Mono Bold, unless file is set	Bold face.
italicFile	string	the bundled JetBrains Mono Italic, unless file is set	Italic face.
boldItalicFile	string	the bundled JetBrains Mono Bold Italic, unless file is set	Bold italic face.
fallbackFile	string	none	Extra font tried for glyphs the main font lacks, for example a symbols or Nerd Font.
size	number	15	Font size in CSS pixels, 6 to 96.

clips

A short animated recording of a terminal app, written by showcase record. Each clip starts a fresh app.

Key	Type	Default	Meaning
id	string	required	File name stem and {id} token. Letters, digits, - and _; must not repeat a shot id.
title	string	the clip's id	Human name, used in the frame title.
caption	string	the clip's title	Caption under the clip in the README table.
alt	string	the app name and the title, as <name>: <title>	Alt text.
steps	ClipStep[]	required	The timeline, run once the app is ready and setup has run.
fps	number	10	Frames per second, 1 to 50.
durationMs	number	60000	Upper bound on the clip length in milliseconds.
maxFrames	number	300	Upper bound on the frames, counted after unchanged frames merge (like RecordedClip.frames). Each distinct frame stays in memory until the clip is encoded. When a recording reaches it, the kit warns, stops recording and writes the frames so far.
tailMs	number	1500	How long to keep recording after the last step, in milliseconds.
formats	ClipFormat[] = ('webp' | 'gif' | 'mp4')[]	['webp', 'gif']	Formats to write. 'mp4' needs ffmpeg on PATH.

clips[].steps

One step of a clip's timeline. Steps run on the clip's frame clock, so a key's effect shows from the next frame.

Form	Meaning
{ keys: Keys }	Keys to press, like a shot's keys.
{ type: string; delayMs?: number }	Text typed literally (no {Key} names), all at once or one character every delayMs.
{ waitFor: string | RegExp }	Wait until this text is on screen (a substring or a RegExp), bounded by timeouts.shotMs.
{ sleep: number }	Pause, in milliseconds, rounded to whole frames.

Path templates

What the validator accepts in each templated key. A path with an unknown token, a missing required token or the wrong ending is an error. {id} is required so shots do not overwrite each other, and so is {lang} once langs has more than one language.

Key	Tokens	Must contain	Must end in
frame.title	{name}, {title}, {id}, {lang} (filled when the image is drawn; not checked by the validator)	nothing	anything
frame.address	{url}, {name}, {title}, {id}, {lang}	nothing	anything
outputs.raw	{lang}, {id}, {slug}	{id}; with more than one language also {lang}	.png
outputs.readme	{lang}, {id}, {slug}	{id}; with more than one language also {lang}	.webp or .png
outputs.clips	{lang}, {id}, {slug}, {ext}	{id}, {ext}; with more than one language also {lang}	.{ext}
outputs.portfolio.dir	{slug}	nothing	anything
outputs.portfolio.publicPath	{slug}	nothing	anything
outputs.portfolio.gallery	{slug}	nothing	.json
hero.output	{lang}, {slug}	nothing	.webp or .png

Keys in the wrong mode

Keys the validator refuses in a mode with a message of its own, rather than “unknown key”. Generated by trying each key in each mode.

Key	Refused in	Message
terminal	url mode	only used in tty mode
clips	url mode	web clips arrive in v0.3; clips only work with target.mode "tty" for now
viewport	tty mode	not used in tty mode (the image size comes from target.cols, target.rows, terminal.font.size and terminal.padding)
colorScheme	tty mode	not used in tty mode (set terminal.theme)
css	tty mode	not used in tty mode
outputs.clips	url mode	web clips arrive in v0.3; clips only work with target.mode "tty" for now
timeouts.readyMs	tty mode	not used in tty mode (set target.readyTimeoutMs)
timeouts.networkIdleMs	tty mode	not used in tty mode
target.url	tty mode	not used in tty mode (the kit runs target.command in a terminal)
target.start	tty mode	not used in tty mode (target.command starts the app)
target.reuseExisting	tty mode	not used in tty mode
target.cdpUrl	tty mode	not used in tty mode
target.pageMatch	tty mode	not used in tty mode
shots[].keys	url mode	only used in tty mode
shots[].restart	url mode	only used in tty mode
target.command	url and cdp mode	only used in tty mode
target.inheritEnv	url and cdp mode	only used in tty mode
target.cols	url and cdp mode	only used in tty mode
target.rows	url and cdp mode	only used in tty mode
target.quitKey	url and cdp mode	only used in tty mode
target.inputDelayMs	url and cdp mode	only used in tty mode