feat(console): add the docs code blocks for the parked docs intro

The docs code blocks and file-type icons (packages/ui exposes the icon-name mapping). They belong to the docs
intro page, which is parked until services/www serves /docs; dev's docs proxy keeps serving /docs.
This commit is contained in:
David Hill
2026-11-05 03:42:02 -06:00
Unverified
parent fd08cfa2af
commit 46d606bf97
9 changed files with 2321 additions and 570 deletions
@@ -0,0 +1,59 @@
// Writes src/component/site/docs-file-icons.ts: the file-type icons the docs use, cut from the
// desktop app's sprite (@opencode/ui), so the site bundles a dozen icons instead of 1,089.
// The names come from the shared mapping (chooseIconName) applied to every code block title in
// the docs content and the filenames on /dev/docs-components, plus each icon's _light variant.
// Run after adding a new kind of file to the docs: bun script/docs-file-icons.ts
import { chooseIconName } from "@opencode/ui/icons/file-type-name"
import { readdirSync } from "node:fs"
import path from "node:path"
const app = path.resolve(import.meta.dir, "..")
const content = path.resolve(app, "../../../services/www/src/docs/content")
const sprite = await Bun.file(path.resolve(app, "../../ui/src/components/file-icons/sprite.svg")).text()
const walk = (dir: string): string[] =>
readdirSync(dir, { withFileTypes: true }).flatMap((entry) =>
entry.isDirectory()
? walk(path.join(dir, entry.name))
: entry.name.endsWith(".mdx")
? [path.join(dir, entry.name)]
: [],
)
const titles = (
await Promise.all(
walk(content).map(async (file) => [...(await Bun.file(file).text()).matchAll(/```\w*\s+title="([^"]+)"/g)]),
)
)
.flat()
.map((match) => match[1])
// Filenames and folders shown on the site that aren't titles in the docs content.
const site = [".env", ".github/workflows/opencode.yml", "mise.toml", "install.sh", "count-lines.ts", "release.md"]
const folders = [".opencode", "agents", "commands", "plugins", "tools", ".github", "workflows"]
const names = new Set([
...[...titles, ...site].map((name) => chooseIconName(name, "file", false)),
...folders.map((name) => chooseIconName(name, "directory", false)),
// The fallbacks.
chooseIconName("unknown", "file", false),
chooseIconName("unknown", "directory", false),
])
const symbol = (name: string) => sprite.match(new RegExp(`<symbol([^>]*)id="${name}"([^>]*)>([\\s\\S]*?)</symbol>`))
const icons = [...names, ...[...names].map((name) => `${name}_light`)].flatMap((name) => {
const match = symbol(name)
if (!match) return []
const attrs = `${match[1]}${match[2]}`.replace(/\s+/g, " ").trim()
const body = match[3].replace(/\s+/g, " ").replace(/>\s+</g, "><").trim()
return [[name, `<svg xmlns="http://www.w3.org/2000/svg" ${attrs}>${body}</svg>`] as const]
})
await Bun.write(
path.join(app, "src/component/site/docs-file-icons.ts"),
`// Generated by script/docs-file-icons.ts from @opencode/ui's file-type sprite. Do not edit.
import type { IconName } from "@opencode/ui/icons/file-type"
export const docsFileIcons: Partial<Record<IconName, string>> = {
${icons.map(([name, svg]) => ` ${name}: ${JSON.stringify(svg)},`).join("\n")}
}
`,
)
console.log(`${icons.length} icons: ${icons.map((icon) => icon[0]).join(", ")}`)
@@ -0,0 +1,162 @@
import { useI18n } from "~/context/i18n"
import { createEffect, createSignal, For, onCleanup, Show, type JSX } from "solid-js"
import { FileTypeIcon } from "./file-type-icon"
import type { DocsVariantKey } from "./settings"
/**
* The frame around a docs code block: a header row with a label (a file name, a terminal mark,
* "Files", "Usage") and a copy button that's always visible. It only shows with a component's
* "Vercel square" option (docs-variants.css); the other options keep their own look, so the frame
* folds away (display: contents) and its header hides.
*/
export function CodeFrame(props: {
variant: DocsVariantKey
kind: "file" | "terminal" | "code" | "tree" | "usage" | "response" | "config"
label?: string
/** The text to copy; leading "$ " prompts are dropped. No copy button without it. */
copy?: string
/** A different terminal mark, for the icon options in the code gallery. */
icon?: "window" | "prompt" | "titlebar"
children: JSX.Element
}) {
return (
<div data-component="code-frame" data-variant={props.variant} data-kind={props.kind} data-icon={props.icon}>
<div data-slot="code-head">
<span data-slot="code-label">
<Show when={props.kind === "file" && props.label}>{(label) => <FileTypeIcon path={label()} />}</Show>
{props.label}
</span>
<Show when={props.copy}>{(text) => <CopyButton text={text()} />}</Show>
</div>
{props.children}
</div>
)
}
/**
* Copy with visible feedback, text only: "Copy" turns to "Copied" for 1.5s (or "Failed" when the
* clipboard refuses), and a polite live region says what happened. The three labels share one
* right-aligned grid cell, so the button keeps the longest label's width and the text's right edge
* never moves.
*/
export function CopyButton(props: { text: string; slot?: "code-copy" | "copy" }) {
const i18n = useI18n()
const [state, setState] = createSignal<"idle" | "copied" | "failed">("idle")
let timer: ReturnType<typeof setTimeout> | undefined
onCleanup(() => clearTimeout(timer))
const show = (next: "copied" | "failed") => {
setState(next)
clearTimeout(timer)
timer = setTimeout(() => setState("idle"), 1500)
}
const copy = () => {
const write = navigator.clipboard?.writeText(props.text.replace(/^\$ /gm, ""))
if (!write) return show("failed")
write.then(
() => show("copied"),
() => show("failed"),
)
}
return (
<>
<button
type="button"
data-slot={props.slot ?? "code-copy"}
data-state={state()}
aria-label={i18n.t("site.code.copy")}
onClick={copy}
>
<span data-slot="copy-labels" aria-hidden="true">
<span data-label="idle">{i18n.t("site.action.copy")}</span>
<span data-label="copied">{i18n.t("site.action.copied")}</span>
<span data-label="failed">{i18n.t("site.code.failed")}</span>
</span>
</button>
<span data-slot="sr-only" aria-live="polite">
{state() === "copied" ? i18n.t("site.code.copied") : state() === "failed" ? i18n.t("site.code.failedHint") : ""}
</span>
</>
)
}
/**
* Lines with the rest folded away. The folded lines stay in the page (hidden="until-found"), so
* find in page reaches them and opens the block; Copy always copies everything.
* "marker" (the default, chosen 5 Nov 2026) is a plain "⋯ 8 more lines" row in the gutter where the
* lines are, GitHub style, that turns to "Show fewer lines" at the end of the revealed range.
* "fade" and "bar" are the older options, kept for comparison in the gallery.
*/
export function CodeCollapse(props: {
style?: "marker" | "fade" | "bar"
visible: JSX.Element
hidden: JSX.Element
count: number
}) {
const [open, setOpen] = createSignal(false)
let folded: HTMLDivElement | undefined
createEffect(() => {
if (!folded) return
if (open()) folded.removeAttribute("hidden")
else folded.setAttribute("hidden", "until-found")
})
const style = () => props.style ?? "marker"
const name = () => (open() ? `Show fewer lines, hide ${props.count}` : `Show ${props.count} more lines`)
return (
<div data-slot="code-collapse" data-style={style()} data-open={open() ? "" : undefined}>
<div data-slot="collapse-visible">{props.visible}</div>
<div
data-slot="collapse-folded"
ref={(el) => {
folded = el
el.setAttribute("hidden", "until-found")
el.addEventListener("beforematch", () => setOpen(true))
}}
>
{props.hidden}
</div>
<button
type="button"
data-slot="code-expand"
aria-expanded={open()}
aria-label={name()}
onClick={() => setOpen(!open())}
>
<Show when={style() === "marker"} fallback={open() ? "Show fewer lines" : `Show ${props.count} more lines`}>
<span data-slot="expand-mark" aria-hidden="true">
⋯
</span>
{open() ? "Show fewer lines" : `${props.count} more lines`}
</Show>
</button>
</div>
)
}
/** Numbered lines for the gallery (marks, focus dimming, a start number, no gutter when plain). */
export function CodeLines(props: {
lines: string[]
mark?: number[]
focus?: number[]
plain?: boolean
start?: number
}) {
return (
<pre data-component="code-lines" data-plain={props.plain ? "" : undefined}>
<For each={props.lines}>
{(line, index) => {
const n = (props.start ?? 1) + index()
return (
<code
data-line={n}
data-mark={props.mark?.includes(n) ? "" : undefined}
data-dim={props.focus && !props.focus.includes(n) ? "" : undefined}
>
{line || " "}
{"\n"}
</code>
)
}}
</For>
</pre>
)
}
@@ -0,0 +1,689 @@
import { createSignal, For, Show, type JSX } from "solid-js"
import { CodeCollapse, CodeFrame, CodeLines, CopyButton } from "./code-frame"
import { FileTree, FileTypeIcon } from "./file-type-icon"
import { docsInstalls } from "~/lib/docs-content"
/**
* Every docs code block type at once, in Vercel square (the chosen code style), whatever the
* kitchen sink's switchers say: docs-variants.css styles [data-slot="code-gallery"] as option 6.
* Content is from the docs (services/www/src/docs/content), with models reading Claude Opus 5.5.
*/
export function DocsCodeGallery(props: { reference?: boolean }) {
return (
<div data-slot="code-gallery">
<Item name="Plain code" when="A snippet that isn't a file and isn't run, like a type or a short example.">
<CodeFrame variant="code" kind="code" label="TypeScript" copy={permissionType}>
<pre>
<code>{permissionType}</code>
</pre>
</CodeFrame>
</Item>
<Item name="File name header" when="Tells the reader which file the code goes in.">
<CodeFrame variant="codeTitle" kind="file" label="opencode.jsonc" copy={configFile}>
<pre>
<code>{configFile}</code>
</pre>
</CodeFrame>
</Item>
<Show when={!props.reference}>
<Item
name="File icon options"
when="The desktop app's file-type icons, in colour or in the label grey. ★ Colour is recommended."
>
<div data-slot="gallery-options">
<For
each={
[
["color", "★ Colour (the desktop app's icons)"],
["mono", "Monochrome (currentColor)"],
] as const
}
>
{([mode, name]) => (
<div data-file-icons={mode}>
<p data-slot="option-name">{name}</p>
<Tabs files label="Files" items={files} />
<CodeFrame variant="fileTree" kind="tree" label="Files">
<FileTree tree={tree} />
</CodeFrame>
</div>
)}
</For>
</div>
</Item>
</Show>
<Item name="Multi-file tabs" when="One change across several files, one tab per file.">
<Tabs files label="Files" items={files} />
</Item>
<Item name="Package-manager tabs" when="The same install command in npm, bun, pnpm and yarn.">
<Tabs
label="Package manager"
items={docsInstalls
.filter((item) => ["npm", "bun", "pnpm", "yarn"].includes(item.label))
.map((item) => ({ label: item.label, code: item.code, shell: true }))}
/>
</Item>
<Item name="Terminal command" when="Something to paste into a shell; Copy drops the $ prompt.">
<Terminal lines={['$ opencode run "Explain this repository"']} />
</Item>
<Show when={!props.reference}>
<Item
name="Terminal icon options"
when="The mark in a terminal's header, 16px at a 1.5 stroke like the file mark. ★ Window is recommended."
>
<div data-slot="gallery-options">
<For
each={
[
["window", "★ Window (a square with a prompt)"],
["prompt", "Prompt (the chevron and cursor alone)"],
["titlebar", "Window with a title bar"],
] as const
}
>
{([icon, name]) => (
<div>
<p data-slot="option-name">{name}</p>
<CodeFrame variant="terminal" kind="terminal" label="Terminal" icon={icon} copy="$ opencode">
<pre data-component="code-block">
<code>
<span data-token="prompt">$ </span>
<span data-token="command">opencode</span>
</code>
</pre>
</CodeFrame>
</div>
)}
</For>
</div>
</Item>
</Show>
<Item name="Command with output" when="What the reader should see after a command, so they can check it worked.">
<Terminal
lines={[
"$ opencode pair",
"",
" Open a link to connect. Links work once and expire in 5 minutes.",
"",
" http://127.0.0.1:49374/auth/connect/...",
]}
copy="opencode pair"
/>
</Item>
<Item name="Long multi-command script" when="A setup run top to bottom, one command per line.">
<Terminal
lines={[
"$ curl -fsSL https://opencode.ai/v2/install | bash",
"$ cd my-app",
"$ opencode auth login",
'$ opencode run --model opencode/claude-opus-5-5 "Add a health check route"',
"$ opencode service restart",
]}
/>
</Item>
<Item name="Line numbers" when="Only when the text refers to lines by number.">
<CodeFrame variant="codeLines" kind="file" label=".opencode/tools/count-lines.ts" copy={countLines.join("\n")}>
<CodeLines lines={countLines} />
</CodeFrame>
</Item>
<Item name="Highlighted lines" when="Points at the lines that matter in a longer example.">
<CodeFrame variant="codeLines" kind="file" label=".opencode/tools/count-lines.ts" copy={countLines.join("\n")}>
<CodeLines lines={countLines} mark={[4, 5]} plain />
</CodeFrame>
</Item>
<Item name="Diff" when="Shows a change, like a renamed key, a migration or a fix.">
<CodeFrame variant="codeDiff" kind="file" label="opencode.jsonc" copy={diffAfter}>
<pre data-component="code-diff">
<For each={diff}>
{([sign, line]) => (
<code data-diff={sign}>
<span data-slot="sign">{sign}</span>
{line}
{"\n"}
</code>
)}
</For>
</pre>
</CodeFrame>
</Item>
<Item name="Focus and collapse" when="A long example where only part matters; the rest folds away.">
<CodeFrame
variant="codeLines"
kind="file"
label="opencode.jsonc"
copy={[...focusLines, ...hiddenLines].join("\n")}
>
<CodeCollapse
count={hiddenLines.length}
visible={<CodeLines lines={focusLines} focus={[3, 4, 5, 6, 7]} plain />}
hidden={<CodeLines lines={hiddenLines} start={focusLines.length + 1} plain />}
/>
</CodeFrame>
</Item>
<Show when={!props.reference}>
<Item
name="Collapse options"
when="Three ways to fold lines away. ★ The gutter marker is the default; the other two are old."
>
<div data-slot="gallery-options" data-stack="">
<For
each={
[
["marker", "★ Gutter marker, in place (GitHub, Expressive Code)"],
["fade", "Old · fade with a centred button (Vercel, Mintlify)"],
["bar", "Old · full-width bar"],
] as const
}
>
{([style, name]) => (
<div>
<p data-slot="option-name">{name}</p>
<CodeFrame
variant="codeLines"
kind="file"
label="opencode.jsonc"
copy={[...focusLines, ...hiddenLines].join("\n")}
>
<CodeCollapse
style={style}
count={hiddenLines.length}
visible={<CodeLines lines={focusLines} plain />}
hidden={<CodeLines lines={hiddenLines} start={focusLines.length + 1} plain />}
/>
</CodeFrame>
</div>
)}
</For>
</div>
</Item>
</Show>
<Item name="Long lines" when="Wider than the column, so the block scrolls sideways; code never wraps.">
<Terminal
lines={[
'$ opencode run --standalone --model opencode/claude-opus-5-5 "Review this repository for correctness and summarize any issues with file and line references"',
]}
/>
</Item>
<Item name="Config (opencode.jsonc)" when="Config is JSON with comments; $schema gives editor completion.">
<CodeFrame variant="codeTitle" kind="file" label="opencode.jsonc" copy={permissionsFile}>
<pre>
<code>{permissionsFile}</code>
</pre>
</CodeFrame>
</Item>
<Item name="YAML" when="Agent frontmatter and CI workflows.">
<CodeFrame variant="codeTitle" kind="file" label=".github/workflows/opencode.yml" copy={workflow}>
<pre>
<code>{workflow}</code>
</pre>
</CodeFrame>
</Item>
<Item name=".env file" when="Secrets and switches set outside the config, loaded by your shell or CI.">
<CodeFrame variant="codeTitle" kind="file" label=".env" copy={env}>
<pre>
<code>{env}</code>
</pre>
</CodeFrame>
</Item>
<Item name="File tree" when="Shows where files go.">
<CodeFrame variant="fileTree" kind="tree" label="Files">
<FileTree tree={tree} />
</CodeFrame>
</Item>
<Item name="CLI reference" when="Each command, its flags and an example.">
<CodeFrame variant="cli" kind="usage" label="Usage" copy="opencode run [message..]">
<pre>
<code>opencode run [message..]</code>
</pre>
</CodeFrame>
<Table
head={["Flag", "Short", "Description"]}
kinds={["code", "code", "text"]}
rows={[
["--model", "-m", "Model to use, as provider/model"],
["--continue", "-c", "Continue the last session"],
["--file", "-f", "Attach a file to the message"],
["--standalone", "", "Run a private server for this command"],
]}
/>
</Item>
<Item name="Config reference table" when="Every option with its type, default and meaning.">
<CodeFrame variant="config" kind="config" label="opencode.jsonc options">
<Table
head={["Option", "Type", "Default", "Description"]}
kinds={["code", "type", "code", "text"]}
rows={[
["model", "string", "", "The default model, as provider/model"],
["instructions", "string[]", "[]", "Extra instruction files, as paths or globs"],
["compaction.auto", "boolean", "true", "Summarize near the context limit"],
["permissions", "Rule[]", "[]", "Ordered allow, deny and ask rules"],
]}
/>
</CodeFrame>
</Item>
<Item name="API request and response" when="An endpoint, its parameters, a request and what comes back.">
<ApiExample />
</Item>
<Item name="Code inside a callout" when="A tip or warning that carries a command.">
<aside data-component="callout" data-type="tip" aria-label="Tip">
<strong>Tip</strong>
<div>
<p>Skip project instructions for one run.</p>
<Terminal lines={["$ OPENCODE_DISABLE_PROJECT_CONFIG=1 opencode"]} />
</div>
</aside>
</Item>
<Item name="Code inside steps" when="Setup steps where each step runs or adds something.">
<ol data-slot="gallery-steps">
<li>
<p>
<strong>Create the plugin.</strong> Add <code>.opencode/plugins/notify.ts</code>.
</p>
<CodeFrame variant="codeTitle" kind="file" label=".opencode/plugins/notify.ts" copy={notifyPlugin}>
<pre>
<code>{notifyPlugin}</code>
</pre>
</CodeFrame>
</li>
<li>
<p>
<strong>Restart OpenCode.</strong> Plugins load on start.
</p>
<Terminal lines={["$ opencode service restart"]} />
</li>
</ol>
</Item>
<Item name="Inline code" when="Names in running text: files, keys, commands.">
<p>
Set <code>model</code> to <code>opencode/claude-opus-5-5</code> in <code>opencode.jsonc</code>, then run{" "}
<code>opencode run "fix the tests"</code>.
</p>
</Item>
</div>
)
}
function Item(props: { name: string; when: string; children: JSX.Element }) {
return (
<figure data-slot="gallery-item">
<figcaption>
<b>{props.name}</b> · {props.when}
</figcaption>
{props.children}
</figure>
)
}
// A shell block: "$ " lines are commands (coloured, copied without the prompt), the rest output.
function Terminal(props: { lines: string[]; copy?: string; label?: string }) {
const commands = () => props.lines.filter((line) => line.startsWith("$ ")).join("\n")
return (
<CodeFrame variant="terminal" kind="terminal" label={props.label ?? "Terminal"} copy={props.copy ?? commands()}>
<pre data-component="code-block">
<code>
<For each={props.lines}>
{(line, index) => (
<>
<Show when={line.startsWith("$ ")} fallback={<span data-token="output">{line}</span>}>
<span data-token="prompt">$ </span>
<Shell command={line.slice(2)} />
</Show>
{index() < props.lines.length - 1 ? "\n" : ""}
</>
)}
</For>
</code>
</pre>
</CodeFrame>
)
}
// A rough shell highlighter: the first word, flags, quoted strings, URLs, pipes and assignments.
function Shell(props: { command: string }) {
const parts = () => props.command.match(/"[^"]*"|'[^']*'|\s+|[^\s]+/g) ?? []
const first = () => parts().findIndex((part) => part.trim() && !/^[A-Z_]+=/.test(part))
const token = (part: string, index: number) => {
if (!part.trim()) return undefined
if (index === first()) return "command"
if (/^[A-Z_]+=/.test(part) || part.startsWith("-")) return "flag"
if (/^["']/.test(part) || /^https?:/.test(part)) return "string"
if (part === "|" || part === "&&") return "operator"
return undefined
}
return (
<For each={parts()}>
{(part, index) => (
<Show when={token(part, index())} fallback={part}>
{(kind) => <span data-token={kind()}>{part}</span>}
</Show>
)}
</For>
)
}
// A reference table: "code" cells are mono names in ink, "type" cells muted mono, the rest text.
function Table(props: { head: string[]; kinds: ("code" | "type" | "text")[]; rows: string[][] }) {
return (
<div data-slot="gallery-table">
<table>
<thead>
<tr>
<For each={props.head}>{(cell) => <th>{cell}</th>}</For>
</tr>
</thead>
<tbody>
<For each={props.rows}>
{(row) => (
<tr>
<For each={row}>
{(cell, index) => (
<td>
<Show when={cell && props.kinds[index()] !== "text" && props.kinds[index()]} fallback={cell}>
{(kind) => (kind() === "code" ? <code>{cell}</code> : <span data-slot="ref-type">{cell}</span>)}
</Show>
</td>
)}
</For>
</tr>
)}
</For>
</tbody>
</table>
</div>
)
}
/**
* The API reference's endpoint card (option 7, the default): the method and path in the header, the
* description, the parameters as a definition table, then a request and the responses by status,
* all on the code surface. Shared by the gallery and the kitchen sink's API sample.
*/
export function ApiExample() {
const [status, setStatus] = createSignal(0)
const responses = [
{ label: "200 OK", body: response },
{ label: "404 Not found", body: notFound },
]
return (
<div data-component="api-operation">
<p data-slot="api-head">
<span data-component="badge" data-method="get">
GET
</span>{" "}
<code>/session/{"{sessionID}"}/message</code>
</p>
<div data-slot="api-body">
<p>List the messages in a session, oldest first.</p>
<div data-slot="api-table">
<table>
<thead>
<tr>
<th>Name</th>
<th>In</th>
<th>Type</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<For each={apiParameters}>
{(row) => (
<tr>
<td>
<code>{row.name}</code>
</td>
<td>{row.in}</td>
<td>
<span data-slot="ref-type">{row.type}</span>
</td>
<td>
<span data-slot="ref-required" data-required={row.required ? "" : undefined}>
{row.required ? "Required" : "Optional"}
</span>
</td>
<td>{row.description}</td>
</tr>
)}
</For>
</tbody>
</table>
</div>
<Terminal lines={["$ curl http://127.0.0.1:4096/session/ses_01JC4X/message?limit=1"]} label="Request" />
<div data-component="code-tabs" data-status="">
<div data-slot="tabs" role="tablist" aria-label="Response status">
<For each={responses}>
{(item, index) => (
<button
type="button"
role="tab"
aria-selected={status() === index() ? "true" : "false"}
tabIndex={status() === index() ? 0 : -1}
onClick={() => setStatus(index())}
>
{item.label}
</button>
)}
</For>
</div>
<div data-slot="code" role="tabpanel">
<code>{responses[status()].body}</code>
<CopyButton slot="copy" text={responses[status()].body} />
</div>
</div>
</div>
</div>
)
}
const apiParameters = [
{ name: "sessionID", in: "path", type: "string", required: true, description: "The session to read." },
{ name: "limit", in: "query", type: "number", required: false, description: "How many messages to return." },
]
const notFound = `{
"error": "session_not_found",
"message": "No session with ID ses_01JC4X."
}`
// Tabs in the block's header (package managers or files), with a working Copy for the open tab.
function Tabs(props: { label: string; files?: boolean; items: { label: string; code: string; shell?: boolean }[] }) {
const [open, setOpen] = createSignal(0)
const keyDown = (event: KeyboardEvent, index: number) => {
if (event.key !== "ArrowRight" && event.key !== "ArrowLeft") return
event.preventDefault()
const next = (index + (event.key === "ArrowRight" ? 1 : -1) + props.items.length) % props.items.length
setOpen(next)
const tab = (event.currentTarget as HTMLElement).parentElement?.children[next]
if (tab instanceof HTMLElement) tab.focus()
}
return (
<div data-component="code-tabs" data-files={props.files ? "" : undefined}>
<div data-slot="tabs" role="tablist" aria-label={props.label}>
<For each={props.items}>
{(item, index) => (
<button
type="button"
role="tab"
aria-selected={open() === index() ? "true" : "false"}
tabIndex={open() === index() ? 0 : -1}
onClick={() => setOpen(index())}
onKeyDown={(event) => keyDown(event, index())}
>
<Show when={props.files}>
<FileTypeIcon path={item.label} />
</Show>
{item.label}
</button>
)}
</For>
</div>
<div data-slot="code" role="tabpanel">
<code>
<Show when={props.items[open()].shell} fallback={props.items[open()].code}>
<Shell command={props.items[open()].code} />
</Show>
</code>
<CopyButton slot="copy" text={props.items[open()].code} />
</div>
</div>
)
}
const permissionType = `type Permission = {
action: string
resource: string
effect: "allow" | "deny" | "ask"
}`
const configFile = `{
"$schema": "https://opencode.ai/config.json",
"model": "opencode/claude-opus-5-5",
"instructions": ["AGENTS.md"]
}`
const files = [
{ label: "opencode.jsonc", code: configFile },
{
label: "AGENTS.md",
code: `# Project instructions
- Run \`bun typecheck\` after changing TypeScript.
- Keep database queries in \`src/database\`.`,
},
{
label: ".opencode/agents/reviewer.md",
code: `---
description: Reviews changes for correctness and regressions
mode: subagent
model: opencode/claude-opus-5-5
---
Review the current changes. List findings in severity order.`,
},
]
const countLines = [
'import { tool } from "@opencode-ai/plugin"',
"",
"export default tool({",
' description: "Count lines in a file",',
" args: { path: tool.schema.string() },",
" async execute(args) {",
" const text = await Bun.file(args.path).text()",
' return String(text.split("\\n").length)',
" },",
"})",
]
const diff = [
[" ", "{"],
[" ", ' "model": "opencode/claude-opus-5-5",'],
["+", ' "instructions": ["AGENTS.md"],'],
[" ", ' "permissions": ['],
["-", ' { "action": "shell", "resource": "git push *", "effect": "allow" },'],
["+", ' { "action": "shell", "resource": "git push *", "effect": "ask" },'],
[" ", " ],"],
[" ", "}"],
]
const diffAfter = diff
.filter((entry) => entry[0] !== "-")
.map((entry) => entry[1])
.join("\n")
const focusLines = [
"{",
' "$schema": "https://opencode.ai/config.json",',
' "permissions": [',
" {",
' "action": "shell",',
' "resource": "git push *",',
' "effect": "ask",',
" },",
]
const hiddenLines = [
" ],",
' "experimental": {',
' "policies": [',
' { "action": "provider.use", "resource": "*", "effect": "deny" },',
' { "action": "provider.use", "resource": "opencode", "effect": "allow" },',
" ],",
" },",
"}",
]
const permissionsFile = `{
"$schema": "https://opencode.ai/config.json",
// Ask before any git push; everything else follows the defaults.
"permissions": [
{
"action": "shell",
"resource": "git push *",
"effect": "ask",
},
],
}`
const workflow = `name: OpenCode review
on: [pull_request]
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm install --global @opencode/cli
- run: opencode run --standalone --model opencode/claude-opus-5-5 "Review this repository"`
const env = `# Loaded by your shell or CI, never committed
ANTHROPIC_API_KEY=sk-ant-...
OPENCODE_DISABLE_PROJECT_CONFIG=1`
const tree = `.opencode/
├── agents/
│ └── reviewer.md
├── commands/
│ └── release.md
├── plugins/
│ └── notify.ts
├── tools/
│ └── count-lines.ts
└── opencode.jsonc`
const response = `[
{
"id": "msg_01JC4Y",
"role": "assistant",
"model": "opencode/claude-opus-5-5",
"parts": [{ "type": "text", "text": "The tests pass." }]
}
]`
const notifyPlugin = `export const Notify = async () => ({
"session.idle": async () => console.log("Done"),
})`
@@ -0,0 +1,31 @@
// Generated by script/docs-file-icons.ts from @opencode/ui's file-type sprite. Do not edit.
import type { IconName } from "@opencode/ui/icons/file-type"
export const docsFileIcons: Partial<Record<IconName, string>> = {
Markdown:
'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><path fill="#42a5f5" d="m14 10-4 3.5L6 10H4v12h4v-6l2 2 2-2v6h4V10zm12 6v-6h-4v6h-4l6 8 6-8z"></path></svg>',
Json: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 -960 960 960"><path fill="#f9a825" d="M560-160v-80h120q17 0 28.5-11.5T720-280v-80q0-38 22-69t58-44v-14q-36-13-58-44t-22-69v-80q0-17-11.5-28.5T680-720H560v-80h120q50 0 85 35t35 85v80q0 17 11.5 28.5T840-560h40v160h-40q-17 0-28.5 11.5T800-360v80q0 50-35 85t-85 35zm-280 0q-50 0-85-35t-35-85v-80q0-17-11.5-28.5T120-400H80v-160h40q17 0 28.5-11.5T160-600v-80q0-50 35-85t85-35h120v80H280q-17 0-28.5 11.5T240-680v80q0 38-22 69t-58 44v14q36 13 58 44t22 69v80q0 17 11.5 28.5T280-240h120v80z" ></path></svg>',
Document:
'<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24"><path d="M0 0h24v24H0z"></path><path fill="#42a5f5" d="M8 16h8v2H8zm0-4h8v2H8zm6-10H6c-1.1 0-2 .9-2 2v16c0 1.1.89 2 1.99 2H18c1.1 0 2-.9 2-2V8zm4 18H6V4h7v5h5z" ></path></svg>',
Typescript:
'<svg xmlns="http://www.w3.org/2000/svg" xml:space="preserve" viewBox="0 0 16 16"><path fill="#0288d1" d="M2 2v12h12V2zm4 6h3v1H8v4H7V9H6zm5 0h2v1h-2v1h1a1.003 1.003 0 0 1 1 1v1a1.003 1.003 0 0 1-1 1h-2v-1h2v-1h-1a1.003 1.003 0 0 1-1-1V9a1.003 1.003 0 0 1 1-1" ></path></svg>',
Nodejs:
'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><path fill="#8bc34a" d="M16 20.003v2h4a2 2 0 0 0 2-2v-2a2 2 0 0 0-2-2h-2v-2h4v-2h-4a2 2 0 0 0-2 2v2a2 2 0 0 0 2 2h2v2Z" ></path><path fill="#8bc34a" d="m16 3.003-12 7v14l4 2h6v-13.5a.5.5 0 0 0-.5-.5h-1a.5.5 0 0 0-.5.5v11.5H8l-2-1.034V11.15l10-5.833 10 5.833v11.703l-10 5.833-1.745-1.022L13 29.253l3 1.75 12-7v-14Z" ></path></svg>',
Readme:
'<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 16 16"><path d="M0 0h24v24H0z"></path><path fill="#42a5f5" d="M8 1C4.136 1 1 4.136 1 8s3.136 7 7 7 7-3.136 7-7-3.136-7-7-7m1 11H7V7.5h2zm0-6H7V4h2z" ></path></svg>',
Tune: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><path fill="#fbc02d" d="M12 10h10v2H12z"></path><path fill="#fbc02d" d="M16 4h2v8h-2zm4 18h10v2H20zm4 2h2v4h-2zm0-20h2v14h-2zM2 18h10v2H2z"></path><path fill="#fbc02d" d="M6 18h2v10H6zM6 4h2v10H6zm10 12h2v12h-2z"></path></svg>',
Yaml: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path fill="#ff5252" d="M13 9h5.5L13 3.5zM6 2h8l6 6v12c0 1.1-.9 2-2 2H6c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2m12 16v-2H9v2zm-4-4v-2H6v2z" ></path></svg>',
Toml: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><path fill="#cfd8dc" d="M4 6V4h8v2H9v7H7V6z"></path><path fill="#ef5350" d="M4 1v1H2v12h2v1H1V1zm8 0v1h2v12h-2v1h3V1z"></path></svg>',
Console:
'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path fill="#ff7043" d="M20 19V7H4v12zm0-16a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H4a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2zm-7 14v-2h5v2zm-3.42-4L5.57 9H8.4l3.3 3.3c.39.39.39 1.03 0 1.42L8.42 17H5.59z" ></path></svg>',
Folder:
'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><path d="m6.922 3.768-.644-.536A1 1 0 0 0 5.638 3H2a1 1 0 0 0-1 1v8a1 1 0 0 0 1 1h12a1 1 0 0 0 1-1V5a1 1 0 0 0-1-1H7.562a1 1 0 0 1-.64-.232" fill="currentColor" ></path></svg>',
FolderTools:
'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><path fill="#1e88e5" d="m13.844 7.536-1.288-1.072A2 2 0 0 0 11.276 6H4a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h24a2 2 0 0 0 2-2V10a2 2 0 0 0-2-2H15.124a2 2 0 0 1-1.28-.464" ></path><path fill="#bbdefb" d="M24.363 19.012 13.364 30 12 28.638l10.988-11zm4.365-2.815.574-.576-.77-.77.624-.623-1.384-1.383-.623.624-.77-.77-.574.575A20.5 20.5 0 0 0 20.155 10l-.81 1.744a24.5 24.5 0 0 1 4.736 3.253l-.488.488 2.923 2.923.488-.488a24.5 24.5 0 0 1 3.252 4.736L32 21.848a20.5 20.5 0 0 0-3.272-5.651" ></path></svg>',
FolderGithub:
'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><path fill="currentColor" d="m13.844 7.536-1.288-1.072A2 2 0 0 0 11.276 6H4a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h24a2 2 0 0 0 2-2V10a2 2 0 0 0-2-2H15.124a2 2 0 0 1-1.28-.464" ></path><path fill="#eceff1" d="M23 10a9.03 9.03 0 0 0-9 9.063 9.08 9.08 0 0 0 6.157 8.609c.45.072.593-.21.593-.453v-1.532c-2.493.544-3.024-1.214-3.024-1.214a2.42 2.42 0 0 0-.998-1.333c-.82-.561.062-.544.062-.544a1.9 1.9 0 0 1 1.377.933 1.925 1.925 0 0 0 2.62.754 1.96 1.96 0 0 1 .566-1.215c-1.998-.227-4.094-1.007-4.094-4.459a3.52 3.52 0 0 1 .927-2.456 3.26 3.26 0 0 1 .09-2.392s.754-.245 2.474.924a8.6 8.6 0 0 1 4.5 0c1.718-1.169 2.476-.924 2.476-.924a3.26 3.26 0 0 1 .088 2.392 3.52 3.52 0 0 1 .927 2.456c0 3.462-2.105 4.223-4.112 4.45a2.17 2.17 0 0 1 .622 1.676v2.484c0 .244.143.533.602.453A9.08 9.08 0 0 0 23 10" ></path></svg>',
FolderGhWorkflows:
'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><path fill="currentColor" d="m13.844 7.536-1.288-1.072A2 2 0 0 0 11.276 6H4a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h24a2 2 0 0 0 2-2V10a2 2 0 0 0-2-2H15.124a2 2 0 0 1-1.28-.464" ></path><path fill="#eceff1" d="M24 22v2h-2a2 2 0 0 1-2-2v-4h2v-6h-6v6h2v4a4.004 4.004 0 0 0 4 4h2v2h6v-6Zm-6-6v-2h2v2Zm10 10h-2v-2h2Z" ></path></svg>',
Toml_light:
'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><path fill="#455a64" d="M4 6V4h8v2H9v7H7V6z"></path><path fill="#ef5350" d="M4 1v1H2v12h2v1H1V1zm8 0v1h2v12h-2v1h3V1z"></path></svg>',
}
@@ -0,0 +1,754 @@
import { createSignal, For, type JSX } from "solid-js"
import { ogImage } from "~/lib/og"
import { CodeFrame, CopyButton } from "./code-frame"
import { ApiExample, DocsCodeGallery } from "./docs-code-gallery"
import { FileTree, FileTypeIcon } from "./file-type-icon"
import type { DocsVariantKey } from "./settings"
/**
* Every docs component sample, grouped as the docs use them. Shared by the review page
* (/dev/docs-components), which wraps each sample in its option switcher and status, and the docs
* reference page (/dev/docs), which shows each one once in its locked option under a plain heading.
* The pages pass in how a group (Section), a sample (Sample) and a review-only note (Note) render.
*/
export function DocsSamples(props: {
Section: (props: { id: DocsSampleSection["id"]; children: JSX.Element }) => JSX.Element
Sample: (props: { variant: DocsVariantKey; label?: string; children: JSX.Element }) => JSX.Element
Note: (props: { children: JSX.Element }) => JSX.Element
/** Extra content at the end of the Docs chrome group (the review page's version notice demo). */
chrome?: JSX.Element
/** Leaves the code gallery's comparisons of old options out. */
reference?: boolean
}) {
const [tab, setTab] = createSignal(0)
const [plan, setPlan] = createSignal(0)
const [file, setFile] = createSignal(0)
return (
<>
<props.Section id="typography">
<props.Sample variant="typography">
<h1>Heading 1 · Configure OpenCode</h1>
<h2>Heading 2 · Providers</h2>
<h3>Heading 3 · Local models</h3>
<h4>Heading 4 · Ollama</h4>
<h5>Heading 5 · Context limits</h5>
<h6>Heading 6 · Notes</h6>
<p data-slot="lead">Lead · OpenCode is an open source coding agent for the terminal, desktop and web.</p>
<p>
Body · Run <code>opencode</code> in a project to open the terminal interface. See{" "}
<a href="#config">Config</a> for every option, or read the{" "}
<a href="https://github.com/anomalyco/opencode" target="_blank">
source on GitHub
</a>
.
</p>
<p>
<small>Small · Requires OpenCode 2.0 or later.</small> The <abbr title="Agent Client Protocol">ACP</abbr>{" "}
server speaks JSON-RPC.
</p>
</props.Sample>
<props.Sample variant="kbd">
<p>
Press <kbd>Ctrl</kbd> + <kbd>X</kbd> then <kbd>N</kbd> to start a new session, or <kbd>Esc</kbd> to stop the
agent.
</p>
</props.Sample>
<props.Sample variant="inlineCode">
<p>
Set <code>model</code> in <code>opencode.jsonc</code>, then run <code>opencode run "fix the tests"</code>.
</p>
</props.Sample>
</props.Section>
<props.Section id="lists">
<props.Sample variant="lists">
<ul>
<li>Agents read your project's instructions first.</li>
<li>
Then they can use tools
<ul>
<li>
<code>read</code>, <code>edit</code> and <code>write</code>
</li>
<li>
<code>bash</code>, with permissions
</li>
</ul>
</li>
<li>Sessions are saved, so you can come back to them.</li>
</ul>
<ol>
<li>Install OpenCode.</li>
<li>
Connect a provider with <code>/connect</code>.
</li>
<li>Ask for a change.</li>
</ol>
<ul data-slot="tasks">
<li>
<input type="checkbox" checked disabled /> Add <code>AGENTS.md</code>
</li>
<li>
<input type="checkbox" disabled /> Configure MCP servers
</li>
</ul>
<ul data-component="downloads">
<li>
<strong>macOS</strong> · <a href="#lists">Apple silicon</a> · <a href="#lists">Intel</a>
</li>
<li>
<strong>Linux</strong> · <a href="#lists">x64</a> · <a href="#lists">ARM64</a>
</li>
</ul>
</props.Sample>
</props.Section>
<props.Section id="blockquote">
<props.Sample variant="blockquote">
<blockquote>
<p>
Homebrew's own <code>brew install opencode</code> formula also installs OpenCode 2. Each release publishes
first to the <code>anomalyco/tap/opencode-v2</code> formula.
</p>
</blockquote>
</props.Sample>
</props.Section>
<props.Section id="callouts">
<props.Sample variant="callout">
<For
each={
[
["note", "Note", "Config files are merged, so a project config overrides only the keys it sets."],
[
"tip",
"Tip",
<>
Run <code>opencode auth login</code> to store a provider key once for every project.
</>,
],
["caution", "Warning", "Plugins run with your permissions. Install only plugins you trust."],
["danger", "Danger", "This deletes every snapshot for the project and can't be undone."],
] as [string, string, JSX.Element][]
}
>
{([type, title, body]) => (
<aside data-component="callout" data-type={type} aria-label={title}>
<strong>{title}</strong>
<div>{body}</div>
</aside>
)}
</For>
<aside data-component="callout" data-type="tip" aria-label="Tip">
<strong>Tip</strong>
<div>
<p>Skip project instructions for one run.</p>
<CodeFrame
variant="terminal"
kind="terminal"
label="Terminal"
copy="$ OPENCODE_DISABLE_PROJECT_CONFIG=1 opencode"
>
<pre data-component="code-block">
<code>
<span data-token="prompt">$ </span>
<span data-token="flag">OPENCODE_DISABLE_PROJECT_CONFIG=1</span>{" "}
<span data-token="command">opencode</span>
</code>
</pre>
</CodeFrame>
</div>
</aside>
</props.Sample>
<props.Note>
v2 uses note, tip and warning. v1 (Starlight) uses note, tip, caution and info. Danger is shown for
completeness.
</props.Note>
</props.Section>
<props.Section id="code-blocks">
<props.Note>
Vercel square is the docs code style. Each block below is a different type, in that style whatever the
switchers further down say. Switch the page theme to see dark.
</props.Note>
<DocsCodeGallery reference={props.reference} />
</props.Section>
<props.Section id="tabs">
<props.Sample variant="tabs">
<div data-component="code-tabs">
<div data-slot="tabs" role="tablist" aria-label="Install method">
<For each={["curl", "npm", "brew"]}>
{(label, index) => (
<button
type="button"
role="tab"
aria-selected={tab() === index() ? "true" : "false"}
tabIndex={tab() === index() ? 0 : -1}
onClick={() => setTab(index())}
>
{label}
</button>
)}
</For>
</div>
<div data-slot="code" role="tabpanel">
<code>
{
[
"curl -fsSL https://opencode.ai/v2/install | bash",
"npm install -g @opencode/cli",
"brew install anomalyco/tap/opencode-v2",
][tab()]
}
</code>
<CopyButton
slot="copy"
text={
[
"curl -fsSL https://opencode.ai/v2/install | bash",
"npm install -g @opencode/cli",
"brew install anomalyco/tap/opencode-v2",
][tab()]
}
/>
</div>
</div>
<div data-component="code-tabs" data-files="">
<div data-slot="tabs" role="tablist" aria-label="Files">
<For each={["opencode.jsonc", "AGENTS.md"]}>
{(label, index) => (
<button
type="button"
role="tab"
aria-selected={file() === index() ? "true" : "false"}
tabIndex={file() === index() ? 0 : -1}
onClick={() => setFile(index())}
>
<FileTypeIcon path={label} />
{label}
</button>
)}
</For>
</div>
<div data-slot="code" role="tabpanel">
<code>
{
[
`{\n "$schema": "https://opencode.ai/config.json",\n "instructions": ["AGENTS.md"]\n}`,
"# Project instructions\n\n- Run bun typecheck after changing TypeScript.",
][file()]
}
</code>
<CopyButton
slot="copy"
text={
[
`{\n "$schema": "https://opencode.ai/config.json",\n "instructions": ["AGENTS.md"]\n}`,
"# Project instructions\n\n- Run bun typecheck after changing TypeScript.",
][file()]
}
/>
</div>
</div>
<div data-component="plan-tabs">
<div role="tablist" aria-label="Plan">
<For each={["Go", "Go Plus"]}>
{(label, index) => (
<button
type="button"
role="tab"
aria-selected={plan() === index() ? "true" : "false"}
onClick={() => setPlan(index())}
>
{label}
</button>
)}
</For>
</div>
<p>
{plan() === 0
? "Go includes 50 requests a day on the fast models."
: "Go Plus raises the limits and adds the large-context models."}
</p>
</div>
</props.Sample>
</props.Section>
<props.Section id="code">
<props.Sample variant="terminal" label="long line">
<CodeFrame
variant="terminal"
kind="terminal"
label="Terminal"
copy={`$ opencode run --model opencode/claude-opus-5-5 "Explain the session runner and list every place that schedules a wake, with file paths"`}
>
<pre data-component="code-block">
<code>
<span data-token="prompt">$ </span>
<span data-token="command">opencode</span> <span data-token="plain">run</span>{" "}
<span data-token="flag">--model</span> <span data-token="string">opencode/claude-opus-5-5</span>{" "}
<span data-token="string">
"Explain the session runner and list every place that schedules a wake, with file paths"
</span>
{"\n\n"}
<span data-token="output">Reading packages/core/src/session/execution.ts…</span>
</code>
</pre>
</CodeFrame>
</props.Sample>
<props.Sample variant="code" label="plain">
<CodeFrame
variant="code"
kind="code"
label="TypeScript"
copy={`export default {\n model: "opencode/claude-opus-5-5",\n}`}
>
<pre>
<code>{`export default {
model: "opencode/claude-opus-5-5",
}`}</code>
</pre>
</CodeFrame>
</props.Sample>
<props.Sample variant="codeTitle">
<CodeFrame
variant="codeTitle"
kind="file"
label="opencode.jsonc"
copy={`{\n "$schema": "https://opencode.ai/config.json",\n "model": "opencode/claude-opus-5-5",\n "permission": { "bash": "ask" }\n}`}
>
<figure data-component="code-figure">
<figcaption>opencode.jsonc</figcaption>
<pre>
<code>{`{
"$schema": "https://opencode.ai/config.json",
"model": "opencode/claude-opus-5-5",
"permission": { "bash": "ask" }
}`}</code>
</pre>
</figure>
</CodeFrame>
</props.Sample>
<props.Sample variant="codeLines" label="highlighted lines">
<CodeFrame
variant="codeLines"
kind="file"
label=".opencode/tools/count-lines.ts"
copy={countLines.join("\n")}
>
<pre data-component="code-lines">
<For each={countLines}>
{(line, index) => (
<code data-line={index() + 1} data-mark={index() === 3 || index() === 4 ? "" : undefined}>
{line || " "}
{"\n"}
</code>
)}
</For>
</pre>
</CodeFrame>
</props.Sample>
<props.Sample variant="codeDiff">
<CodeFrame
variant="codeDiff"
kind="file"
label="opencode.jsonc"
copy={'{\n "model": "opencode/claude-opus-5-5",\n "permission": { "bash": "ask" },\n}'}
>
<pre data-component="code-diff">
<For
each={[
[" ", " {"],
[" ", ' "model": "opencode/claude-opus-5-5",'],
["-", ' "permission": { "bash": "allow" },'],
["+", ' "permission": { "bash": "ask" },'],
[" ", " }"],
]}
>
{([sign, line]) => (
<code data-diff={sign}>
<span data-slot="sign">{sign}</span>
{line.slice(1)}
{"\n"}
</code>
)}
</For>
</pre>
</CodeFrame>
</props.Sample>
</props.Section>
<props.Section id="file-tree">
<props.Sample variant="fileTree">
<CodeFrame variant="fileTree" kind="tree" label="Files">
<FileTree
tree={`.opencode/
└── plugins/
├── concise.ts
├── reviewer.js
└── acme-package/`}
/>
</CodeFrame>
</props.Sample>
</props.Section>
<props.Section id="steps">
<props.Sample variant="steps">
<ol data-component="steps">
<li>
<p>
<strong>Create the plugin.</strong> Add <code>.opencode/plugins/notify.ts</code>.
</p>
<CodeFrame variant="codeTitle" kind="file" label=".opencode/plugins/notify.ts" copy={notifyPlugin}>
<pre>
<code>{notifyPlugin}</code>
</pre>
</CodeFrame>
</li>
<li>
<p>
<strong>Export a hook.</strong> Listen for <code>session.idle</code>.
</p>
</li>
<li>
<p>
<strong>Restart OpenCode.</strong> Plugins load on start.
</p>
<CodeFrame variant="terminal" kind="terminal" label="Terminal" copy="$ opencode service restart">
<pre data-component="code-block">
<code>
<span data-token="prompt">$ </span>
<span data-token="command">opencode</span> service restart
</code>
</pre>
</CodeFrame>
</li>
</ol>
</props.Sample>
</props.Section>
<props.Section id="cards">
<props.Sample variant="cards">
<div data-component="card-group">
<For
each={[
["Plugins", "Hook into sessions, tools and events."],
["Client", "Talk to a running OpenCode server from JavaScript."],
["SDK", "Embed OpenCode in your own app."],
]}
>
{([title, body]) => (
<a data-component="docs-card" href="#cards">
<strong>{title}</strong>
<div>{body}</div>
</a>
)}
</For>
</div>
</props.Sample>
</props.Section>
<props.Section id="tables">
<props.Sample variant="tables" label="simple and wide with code">
<table>
<thead>
<tr>
<th>Key</th>
<th>Action</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<kbd>Ctrl</kbd> <kbd>X</kbd> <kbd>N</kbd>
</td>
<td>New session</td>
</tr>
<tr>
<td>
<kbd>Ctrl</kbd> <kbd>X</kbd> <kbd>M</kbd>
</td>
<td>Switch model</td>
</tr>
</tbody>
</table>
<div data-slot="scroll">
<table>
<thead>
<tr>
<th>Option</th>
<th>Type</th>
<th>Default</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>compaction.auto</code>
</td>
<td>
<code>boolean</code>
</td>
<td>
<code>true</code>
</td>
<td>
Summarize the conversation when it nears the model's context limit, keeping the newest messages.
</td>
</tr>
<tr>
<td>
<code>permission.bash</code>
</td>
<td>
<code>"ask" | "allow" | "deny"</code>
</td>
<td>
<code>"ask"</code>
</td>
<td>Whether shell commands need your approval before they run.</td>
</tr>
</tbody>
</table>
</div>
</props.Sample>
</props.Section>
<props.Section id="badges">
<props.Sample variant="badges">
<p>
<span data-component="badge">New</span> <span data-component="badge">Experimental</span>{" "}
<span data-component="badge">Deprecated</span> <span data-component="badge">v2</span>
</p>
</props.Sample>
</props.Section>
<props.Section id="details">
<props.Sample variant="details">
<details>
<summary>Why does OpenCode ask before running commands?</summary>
<p>
The default <code>bash</code> permission is <code>ask</code>, so nothing runs without your approval.
</p>
</details>
<details>
<summary>Can I use my own model provider?</summary>
<p>Yes. Connect any of 75+ providers, or a local model through an OpenAI-compatible endpoint.</p>
</details>
</props.Sample>
</props.Section>
<props.Section id="media">
<props.Sample variant="media" label="image and video">
<figure>
<img src={ogImage("/docs").src} alt="The OpenCode docs" width="1200" height="630" />
<figcaption>The OpenCode terminal interface.</figcaption>
</figure>
<figure>
<video controls muted playsinline preload="none" poster={ogImage("/docs").src} width="1200" height="630" />
<figcaption>A video embed (no docs page uses one yet).</figcaption>
</figure>
</props.Sample>
</props.Section>
<props.Section id="api">
<props.Sample variant="api">
<ApiExample />
</props.Sample>
</props.Section>
<props.Section id="config">
<props.Sample variant="config">
<CodeFrame variant="config" kind="config" label="opencode.jsonc options">
<dl data-component="config-reference">
<dt>
<code>model</code> <span data-component="badge">string</span>
</dt>
<dd>
The default model, as <code>provider/model</code>.
</dd>
<dt>
<code>instructions</code> <span data-component="badge">string[]</span>
</dt>
<dd>Extra instruction files to load, as paths or globs.</dd>
</dl>
</CodeFrame>
</props.Sample>
</props.Section>
<props.Section id="cli">
<props.Sample variant="cli">
<div data-component="cli-command">
<CodeFrame variant="cli" kind="usage" label="Usage" copy="opencode run [message..]">
<pre>
<code>opencode run [message..]</code>
</pre>
</CodeFrame>
<p>Run OpenCode with a message, without the terminal interface.</p>
<table>
<thead>
<tr>
<th>Flag</th>
<th>Short</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>--model</code>
</td>
<td>
<code>-m</code>
</td>
<td>Model to use, as provider/model</td>
</tr>
<tr>
<td>
<code>--continue</code>
</td>
<td>
<code>-c</code>
</td>
<td>Continue the last session</td>
</tr>
</tbody>
</table>
</div>
</props.Sample>
</props.Section>
<props.Section id="navigation">
<props.Sample variant="breadcrumbs">
<nav aria-label="Breadcrumb" data-component="breadcrumbs">
<a href="#navigation">Docs</a> / <a href="#navigation">Configure</a> /{" "}
<span aria-current="page">Agents</span>
</nav>
</props.Sample>
<props.Sample variant="pagination">
<nav aria-label="Pages" data-component="pagination">
<a href="#navigation" rel="prev">
<small>Previous</small> Config
</a>{" "}
<a href="#navigation" rel="next">
<small>Next</small> Models
</a>
</nav>
</props.Sample>
<props.Sample variant="editLink" label="last updated">
<p data-component="edit-link">
<a href="https://github.com/anomalyco/opencode" target="_blank">
Edit this page on GitHub
</a>{" "}
<span>Last updated 2 Nov 2026</span>
</p>
</props.Sample>
<props.Sample variant="feedback">
<p data-component="feedback">
Was this page helpful? <button type="button">Yes</button> <button type="button">No</button>
</p>
<props.Note>No feedback widget exists in the real docs.</props.Note>
</props.Sample>
<props.Sample variant="switchers" label="language (v1)">
<select aria-label="Language">
<option>English</option>
<option>Deutsch</option>
<option>日本語</option>
<option>العربية</option>
</select>
</props.Sample>
</props.Section>
<props.Section id="chrome">
<props.Sample variant="search" label="the aside's search">
<p data-slot="aside-pointer">The search box is at the top of the right aside.</p>
</props.Sample>
<props.Sample variant="contents" label="the aside's rail">
<p data-slot="aside-pointer">The Contents rail is in the right aside, under the search box.</p>
</props.Sample>
{props.chrome}
</props.Section>
</>
)
}
export type DocsSampleSection = (typeof docsSampleSections)[number]
export const docsSampleSections = [
{
id: "typography",
title: "Typography",
source: "Markdown · prose",
components: ["typography", "kbd", "inlineCode"],
},
{ id: "lists", title: "Lists", source: "Markdown · ul, ol, nested, task", components: ["lists"] },
{ id: "blockquote", title: "Blockquote", source: "Markdown · >", components: ["blockquote"] },
{
id: "callouts",
title: "Callouts",
source: "Callout.astro (note, tip, warning) · Starlight asides",
components: ["callout"],
},
{
id: "code-blocks",
title: "Code block types",
source: "Every code and terminal block type in Vercel square, no switching",
components: [
"tabs",
"code",
"codeTitle",
"codeLines",
"codeDiff",
"terminal",
"fileTree",
"api",
"config",
"cli",
"inlineCode",
],
},
{ id: "tabs", title: "Tabs", source: "CodeTabs.astro · PlanTabs.astro · Starlight Tabs", components: ["tabs"] },
{
id: "code",
title: "Code blocks",
source: "Shiki · title=… transformer · Expressive Code (v1)",
components: ["terminal", "code", "codeTitle", "codeLines", "codeDiff"],
},
{ id: "file-tree", title: "File tree", source: "Starlight FileTree (not used yet)", components: ["fileTree"] },
{ id: "steps", title: "Steps", source: "Numbered lists (v2) · Starlight Steps (v1)", components: ["steps"] },
{ id: "cards", title: "Cards", source: "Card.astro · CardGroup.astro", components: ["cards"] },
{ id: "tables", title: "Tables", source: "Markdown tables (36 pages)", components: ["tables"] },
{ id: "badges", title: "Badges", source: "Not used in the docs yet", components: ["badges"] },
{ id: "details", title: "Details", source: "HTML details/summary", components: ["details"] },
{ id: "media", title: "Images and video", source: "Markdown images · video embeds", components: ["media"] },
{ id: "api", title: "API reference", source: "OpenApiReference.astro · OpenApiSchema.astro", components: ["api"] },
{ id: "config", title: "Config reference", source: "config.json schema · jsonc examples", components: ["config"] },
{ id: "cli", title: "CLI reference", source: "cli/commands.mdx · public/cli.json", components: ["cli"] },
{
id: "navigation",
title: "Page navigation",
source: "Prev/next · breadcrumbs · edit on GitHub · last updated",
components: ["breadcrumbs", "pagination", "editLink", "feedback", "switchers"],
},
{
id: "chrome",
title: "Docs chrome",
source: "docs-lockup · search · Contents rail · V1 notice",
components: ["search", "contents"],
},
] as const satisfies readonly { id: string; title: string; source: string; components: readonly DocsVariantKey[] }[]
const countLines = [
'import { tool } from "@opencode-ai/plugin"',
"",
"export default tool({",
' description: "Count lines in a file",',
" args: { path: tool.schema.string() },",
"})",
]
const notifyPlugin = `export const Notify = async () => ({
"session.idle": async () => console.log("Done"),
})`
@@ -0,0 +1,50 @@
import { chooseIconName } from "@opencode/ui/icons/file-type-name"
import { For, Show } from "solid-js"
import { docsFileIcons } from "./docs-file-icons"
/**
* The desktop app's icon for a file or folder (the shared mapping in @opencode/ui), from the docs'
* subset (docs-file-icons.ts), drawn inline so the folders' currentColor takes the label grey.
* Coloured, with the _light variant in light mode where there is one; inside
* [data-file-icons="mono"] every fill is currentColor instead (docs-variants.css).
*/
export function FileTypeIcon(props: { path: string; directory?: boolean }) {
const type = () => (props.directory ? "directory" : "file")
const name = () => chooseIconName(props.path, type(), false)
const svg = () => docsFileIcons[name()] ?? docsFileIcons[chooseIconName("", type(), false)] ?? ""
const light = () => docsFileIcons[`${name()}_light` as keyof typeof docsFileIcons]
return (
<span data-slot="file-icon" data-icon={name()} aria-hidden="true">
<span data-scheme={light() ? "dark" : undefined} innerHTML={svg()} />
<Show when={light()}>{(markup) => <span data-scheme="light" innerHTML={markup()} />}</Show>
</span>
)
}
/**
* A file tree from "├── name" lines, each file and folder with its icon; folders end in "/". Each
* row carries its depth (--depth, one per four prefix characters) and whether it's a folder, so the
* minimal File tree options can drop the box-drawing prefix and indent or draw guides instead.
*/
export function FileTree(props: { tree: string }) {
const rows = () =>
props.tree.split("\n").map((line) => {
const at = line.search(/[^│├└─\s]/)
const name = line.slice(at)
return { prefix: line.slice(0, at), name, directory: name.endsWith("/"), depth: Math.round(at / 4) }
})
return (
<pre data-component="file-tree" aria-label="Files" tabIndex={0}>
<For each={rows()}>
{(row, index) => (
<span data-slot="tree-row" data-directory={row.directory ? "" : undefined} style={{ "--depth": row.depth }}>
<span data-slot="tree-prefix">{row.prefix}</span>
<FileTypeIcon path={row.name.replace(/\/$/, "")} directory={row.directory} />
<span data-slot="tree-name">{row.name}</span>
{index() < rows().length - 1 ? "\n" : ""}
</span>
)}
</For>
</pre>
)
}
+1
View File
@@ -99,6 +99,7 @@
"./theme/context": "./src/theme/context.tsx",
"./icons/provider": "./src/components/provider-icons/types.ts",
"./icons/file-type": "./src/components/file-icons/types.ts",
"./icons/file-type-name": "./src/components/file-icons/choose-icon-name.ts",
"./icons/app": "./src/components/app-icons/types.ts",
"./fonts/*": "./src/assets/fonts/*",
"./audio/*": "./src/assets/audio/*"
+1 -570
View File
@@ -12,6 +12,7 @@ import {
type FileIconSymbolEvent,
type FileIconSymbolState,
} from "./file-icon-machine"
import { chooseIconName } from "./file-icons/choose-icon-name"
import type { IconName } from "./file-icons/types"
export type FileIconProps = JSX.GSVGAttributes<SVGSVGElement> & {
@@ -183,573 +184,3 @@ function sprite() {
return svg
}
type IconMaps = {
fileNames: Record<string, IconName>
fileExtensions: Record<string, IconName>
folderNames: Record<string, IconName>
defaults: {
file: IconName
folder: IconName
folderOpen: IconName
}
}
const ICON_MAPS: IconMaps = {
fileNames: {
// Documentation files
"readme.md": "Readme",
"changelog.md": "Changelog",
"contributing.md": "Contributing",
"conduct.md": "Conduct",
license: "Certificate",
authors: "Authors",
credits: "Credits",
install: "Installation",
// Node.js files
"package.json": "Nodejs",
"package-lock.json": "Nodejs",
"yarn.lock": "Yarn",
"pnpm-lock.yaml": "Pnpm",
"bun.lock": "Bun",
"bun.lockb": "Bun",
"bunfig.toml": "Bun",
".nvmrc": "Nodejs",
".node-version": "Nodejs",
// Docker files
dockerfile: "Docker",
"docker-compose.yml": "Docker",
"docker-compose.yaml": "Docker",
".dockerignore": "Docker",
// Config files
"jest.config.js": "Jest",
"jest.config.ts": "Jest",
"jest.config.mjs": "Jest",
"vitest.config.js": "Vitest",
"vitest.config.ts": "Vitest",
"tailwind.config.js": "Tailwindcss",
"tailwind.config.ts": "Tailwindcss",
"turbo.json": "Turborepo",
"tsconfig.json": "Tsconfig",
"jsconfig.json": "Jsconfig",
".eslintrc": "Eslint",
".eslintrc.js": "Eslint",
".eslintrc.json": "Eslint",
".prettierrc": "Prettier",
".prettierrc.js": "Prettier",
".prettierrc.json": "Prettier",
"vite.config.js": "Vite",
"vite.config.ts": "Vite",
"webpack.config.js": "Webpack",
"rollup.config.js": "Rollup",
"astro.config.mjs": "AstroConfig",
"astro.config.js": "AstroConfig",
"next.config.js": "Next",
"next.config.mjs": "Next",
"nuxt.config.js": "Nuxt",
"nuxt.config.ts": "Nuxt",
"svelte.config.js": "Svelte",
"gatsby-config.js": "Gatsby",
"remix.config.js": "Remix",
"prisma.schema": "Prisma",
".gitignore": "Git",
".gitattributes": "Git",
makefile: "Makefile",
cmake: "Cmake",
"cargo.toml": "Rust",
"go.mod": "GoMod",
"go.sum": "GoMod",
"requirements.txt": "Python",
"pyproject.toml": "Python",
pipfile: "Python",
"poetry.lock": "Poetry",
gemfile: "Gemfile",
rakefile: "Ruby",
"composer.json": "Php",
"build.gradle": "Gradle",
"pom.xml": "Maven",
"deno.json": "Deno",
"deno.jsonc": "Deno",
"vercel.json": "Vercel",
"netlify.toml": "Netlify",
".env": "Tune",
".env.local": "Tune",
".env.development": "Tune",
".env.production": "Tune",
".env.example": "Tune",
".editorconfig": "Editorconfig",
"robots.txt": "Robots",
"favicon.ico": "Favicon",
browserlist: "Browserlist",
".babelrc": "Babel",
"babel.config.js": "Babel",
"gulpfile.js": "Gulp",
"gruntfile.js": "Grunt",
"capacitor.config.json": "Capacitor",
"ionic.config.json": "Ionic",
"angular.json": "Angular",
".storybook": "Storybook",
"storybook.config.js": "Storybook",
"cypress.config.js": "Cypress",
"playwright.config.js": "Playwright",
"puppeteer.config.js": "Puppeteer",
"wrangler.toml": "Wrangler",
"firebase.json": "Firebase",
supabase: "Supabase",
terraform: "Terraform",
kubernetes: "Kubernetes",
".gitpod.yml": "Gitpod",
".devcontainer": "Vscode",
"travis.yml": "Travis",
"appveyor.yml": "Appveyor",
".circleci": "Circleci",
"renovate.json": "Renovate",
"dependabot.yml": "Dependabot",
"lerna.json": "Lerna",
"nx.json": "Nx",
},
fileExtensions: {
// Test files
"spec.ts": "TestTs",
"test.ts": "TestTs",
"spec.tsx": "TestJsx",
"test.tsx": "TestJsx",
"spec.js": "TestJs",
"test.js": "TestJs",
"spec.jsx": "TestJsx",
"test.jsx": "TestJsx",
// JavaScript/TypeScript
"js.map": "JavascriptMap",
"d.ts": "TypescriptDef",
ts: "Typescript",
tsx: "React_ts",
js: "Javascript",
jsx: "React",
mjs: "Javascript",
cjs: "Javascript",
// Web languages
html: "Html",
htm: "Html",
css: "Css",
scss: "Sass",
sass: "Sass",
less: "Less",
styl: "Stylus",
// Data formats
json: "Json",
xml: "Xml",
yml: "Yaml",
yaml: "Yaml",
toml: "Toml",
hjson: "Hjson",
// Documentation
md: "Markdown",
mdx: "Mdx",
tex: "Tex",
// Programming languages
py: "Python",
pyx: "Python",
pyw: "Python",
rs: "Rust",
go: "Go",
java: "Java",
kt: "Kotlin",
scala: "Scala",
php: "Php",
rb: "Ruby",
cs: "Csharp",
vb: "Visualstudio",
cpp: "Cpp",
cc: "Cpp",
cxx: "Cpp",
c: "C",
h: "H",
hpp: "Hpp",
swift: "Swift",
m: "ObjectiveC",
mm: "ObjectiveCpp",
dart: "Dart",
lua: "Lua",
pl: "Perl",
r: "R",
jl: "Julia",
hs: "Haskell",
elm: "Elm",
ml: "Ocaml",
clj: "Clojure",
cljs: "Clojure",
erl: "Erlang",
ex: "Elixir",
exs: "Elixir",
nim: "Nim",
zig: "Zig",
v: "Vlang",
odin: "Odin",
gleam: "Gleam",
grain: "Grain",
roc: "Rocket",
fs: "Fsharp",
// Shell scripts
sh: "Console",
bash: "Console",
zsh: "Console",
fish: "Console",
ps1: "Powershell",
// Config/build files
cfg: "Settings",
ini: "Settings",
conf: "Settings",
properties: "Settings",
// Media files
svg: "Svg",
png: "Image",
jpg: "Image",
jpeg: "Image",
gif: "Image",
webp: "Image",
bmp: "Image",
ico: "Favicon",
mp4: "Video",
mov: "Video",
avi: "Video",
webm: "Video",
mp3: "Audio",
wav: "Audio",
flac: "Audio",
// Archive files
zip: "Zip",
tar: "Zip",
gz: "Zip",
rar: "Zip",
"7z": "Zip",
// Document files
pdf: "Pdf",
doc: "Word",
docx: "Word",
ppt: "Powerpoint",
pptx: "Powerpoint",
xls: "Document",
xlsx: "Document",
// Database files
sql: "Database",
db: "Database",
sqlite: "Database",
// Other
env: "Tune",
log: "Log",
lock: "Lock",
key: "Key",
pem: "Certificate",
crt: "Certificate",
proto: "Proto",
graphql: "Graphql",
gql: "Graphql",
wasm: "Webassembly",
dockerfile: "Docker",
},
folderNames: {
// Source code
src: "FolderSrc",
source: "FolderSrc",
lib: "FolderLib",
libs: "FolderLib",
// Testing
test: "FolderTest",
tests: "FolderTest",
testing: "FolderTest",
spec: "FolderTest",
specs: "FolderTest",
__tests__: "FolderTest",
e2e: "FolderTest",
integration: "FolderTest",
unit: "FolderTest",
cypress: "FolderCypress",
// Dependencies
node_modules: "FolderNode",
vendor: "FolderPackages",
packages: "FolderPackages",
deps: "FolderPackages",
// Build/dist
build: "FolderBuildkite",
dist: "FolderDist",
out: "FolderDist",
output: "FolderDist",
target: "FolderTarget",
// Configuration
config: "FolderConfig",
configs: "FolderConfig",
configuration: "FolderConfig",
settings: "FolderConfig",
env: "FolderEnvironment",
environments: "FolderEnvironment",
// Docker
docker: "FolderDocker",
dockerfiles: "FolderDocker",
containers: "FolderDocker",
// Documentation
docs: "FolderDocs",
doc: "FolderDocs",
documentation: "FolderDocs",
readme: "FolderDocs",
// Public/assets
public: "FolderPublic",
static: "FolderPublic",
assets: "FolderImages",
images: "FolderImages",
img: "FolderImages",
icons: "FolderImages",
media: "FolderImages",
fonts: "FolderFont",
styles: "FolderCss",
stylesheets: "FolderCss",
css: "FolderCss",
sass: "FolderSass",
scss: "FolderSass",
less: "FolderLess",
// Scripts
scripts: "FolderScripts",
script: "FolderScripts",
tools: "FolderTools",
utils: "FolderUtils",
utilities: "FolderUtils",
helpers: "FolderHelper",
// Framework specific
components: "FolderComponents",
component: "FolderComponents",
views: "FolderViews",
view: "FolderViews",
layouts: "FolderLayout",
layout: "FolderLayout",
templates: "FolderTemplate",
template: "FolderTemplate",
hooks: "FolderHook",
hook: "FolderHook",
store: "FolderStore",
stores: "FolderStore",
state: "FolderNgrxStore",
reducers: "FolderReduxReducer",
reducer: "FolderReduxReducer",
services: "FolderApi",
service: "FolderApi",
api: "FolderApi",
apis: "FolderApi",
routes: "FolderRoutes",
route: "FolderRoutes",
routing: "FolderRoutes",
middleware: "FolderMiddleware",
middlewares: "FolderMiddleware",
controllers: "FolderController",
controller: "FolderController",
models: "FolderDatabase",
model: "FolderDatabase",
schemas: "FolderDatabase",
schema: "FolderDatabase",
migrations: "FolderDatabase",
migration: "FolderDatabase",
seeders: "FolderSeeders",
seeder: "FolderSeeders",
// TypeScript
types: "FolderTypescript",
typing: "FolderTypescript",
typings: "FolderTypescript",
"@types": "FolderTypescript",
interfaces: "FolderInterface",
interface: "FolderInterface",
// Mobile
android: "FolderAndroid",
ios: "FolderIos",
mobile: "FolderMobile",
flutter: "FolderFlutter",
// Infrastructure
kubernetes: "FolderKubernetes",
k8s: "FolderKubernetes",
terraform: "FolderTerraform",
aws: "FolderAws",
azure: "FolderAzurePipelines",
firebase: "FolderFirebase",
supabase: "FolderSupabase",
vercel: "FolderVercel",
netlify: "FolderNetlify",
// CI/CD
".github": "FolderGithub",
".gitlab": "FolderGitlab",
".circleci": "FolderCircleci",
ci: "FolderCi",
".ci": "FolderCi",
workflows: "FolderGhWorkflows",
// Git
".git": "FolderGit",
// Development tools
".vscode": "FolderVscode",
".idea": "FolderIntellij",
".cursor": "FolderCursor",
".devcontainer": "FolderContainer",
".storybook": "FolderStorybook",
// Localization
i18n: "FolderI18n",
locales: "FolderI18n",
locale: "FolderI18n",
lang: "FolderI18n",
languages: "FolderI18n",
// Other common patterns
temp: "FolderTemp",
tmp: "FolderTemp",
logs: "FolderLog",
log: "FolderLog",
backup: "FolderBackup",
backups: "FolderBackup",
examples: "FolderExamples",
example: "FolderExamples",
demo: "FolderExamples",
demos: "FolderExamples",
samples: "FolderExamples",
sample: "FolderExamples",
fixtures: "FolderTest",
mocks: "FolderMock",
mock: "FolderMock",
data: "FolderDatabase",
database: "FolderDatabase",
db: "FolderDatabase",
sql: "FolderDatabase",
prisma: "FolderPrisma",
drizzle: "FolderDrizzle",
// Security
security: "FolderSecure",
auth: "FolderSecure",
authentication: "FolderSecure",
authorization: "FolderSecure",
keys: "FolderKeys",
certs: "FolderKeys",
certificates: "FolderKeys",
// Content
content: "FolderContent",
posts: "FolderContent",
articles: "FolderContent",
blog: "FolderContent",
// Functions
functions: "FolderFunctions",
function: "FolderFunctions",
lambda: "FolderFunctions",
lambdas: "FolderFunctions",
serverless: "FolderServerless",
// Jobs/tasks
jobs: "FolderJob",
job: "FolderJob",
tasks: "FolderTasks",
task: "FolderTasks",
cron: "FolderTasks",
queue: "FolderQueue",
queues: "FolderQueue",
// Desktop platforms
desktop: "FolderDesktop",
windows: "FolderWindows",
macos: "FolderMacos",
linux: "FolderLinux",
},
defaults: {
file: "Document",
folder: "Folder",
folderOpen: "FolderOpen",
},
}
const toOpenVariant = (icon: IconName): IconName => {
if (!icon.startsWith("Folder")) return icon
if (icon.endsWith("_light")) {
// SAFETY: the icon generator writes an `Open` variant for every folder icon, light ones included.
return icon.replace("_light", "Open_light") as IconName
}
if (!icon.endsWith("Open")) {
// SAFETY: the icon generator writes an `Open` variant for every folder icon.
return (icon + "Open") as IconName
}
return icon
}
const basenameOf = (p: string) => p.split("\\").join("/").split("/").filter(Boolean).pop() ?? ""
const folderNameVariants = (name: string) => {
const n = name.toLowerCase()
return [n, `.${n}`, `_${n}`, `__${n}__`]
}
const dottedSuffixesDesc = (name: string) => {
const n = name.toLowerCase()
const idxs: number[] = []
for (let i = 0; i < n.length; i++) if (n[i] === ".") idxs.push(i)
const out = new Set<string>()
out.add(n) // allow exact whole-name "extensions" like "dockerfile"
for (const i of idxs) if (i + 1 < n.length) out.add(n.slice(i + 1))
return Array.from(out).sort((a, b) => b.length - a.length) // longest first
}
export function chooseIconName(path: string, type: "directory" | "file", expanded: boolean): IconName {
const base = basenameOf(path)
const baseLower = base.toLowerCase()
if (type === "directory") {
for (const cand of folderNameVariants(baseLower)) {
const icon = ICON_MAPS.folderNames[cand]
if (icon) return expanded ? toOpenVariant(icon) : icon
}
return expanded ? ICON_MAPS.defaults.folderOpen : ICON_MAPS.defaults.folder
}
const byName = ICON_MAPS.fileNames[baseLower]
if (byName) return byName
for (const ext of dottedSuffixesDesc(baseLower)) {
const icon = ICON_MAPS.fileExtensions[ext]
if (icon) return icon
}
return ICON_MAPS.defaults.file
}
@@ -0,0 +1,574 @@
// Which file-type icon a path gets (FileIcon in file-icon.tsx, and the docs code blocks on the
// website). Kept apart from FileIcon so a caller can map names without bundling the sprite.
import type { IconName } from "./types"
type IconMaps = {
fileNames: Record<string, IconName>
fileExtensions: Record<string, IconName>
folderNames: Record<string, IconName>
defaults: {
file: IconName
folder: IconName
folderOpen: IconName
}
}
const ICON_MAPS: IconMaps = {
fileNames: {
// Documentation files
"readme.md": "Readme",
"changelog.md": "Changelog",
"contributing.md": "Contributing",
"conduct.md": "Conduct",
license: "Certificate",
authors: "Authors",
credits: "Credits",
install: "Installation",
// Node.js files
"package.json": "Nodejs",
"package-lock.json": "Nodejs",
"yarn.lock": "Yarn",
"pnpm-lock.yaml": "Pnpm",
"bun.lock": "Bun",
"bun.lockb": "Bun",
"bunfig.toml": "Bun",
".nvmrc": "Nodejs",
".node-version": "Nodejs",
// Docker files
dockerfile: "Docker",
"docker-compose.yml": "Docker",
"docker-compose.yaml": "Docker",
".dockerignore": "Docker",
// Config files
"jest.config.js": "Jest",
"jest.config.ts": "Jest",
"jest.config.mjs": "Jest",
"vitest.config.js": "Vitest",
"vitest.config.ts": "Vitest",
"tailwind.config.js": "Tailwindcss",
"tailwind.config.ts": "Tailwindcss",
"turbo.json": "Turborepo",
"tsconfig.json": "Tsconfig",
"jsconfig.json": "Jsconfig",
".eslintrc": "Eslint",
".eslintrc.js": "Eslint",
".eslintrc.json": "Eslint",
".prettierrc": "Prettier",
".prettierrc.js": "Prettier",
".prettierrc.json": "Prettier",
"vite.config.js": "Vite",
"vite.config.ts": "Vite",
"webpack.config.js": "Webpack",
"rollup.config.js": "Rollup",
"astro.config.mjs": "AstroConfig",
"astro.config.js": "AstroConfig",
"next.config.js": "Next",
"next.config.mjs": "Next",
"nuxt.config.js": "Nuxt",
"nuxt.config.ts": "Nuxt",
"svelte.config.js": "Svelte",
"gatsby-config.js": "Gatsby",
"remix.config.js": "Remix",
"prisma.schema": "Prisma",
".gitignore": "Git",
".gitattributes": "Git",
makefile: "Makefile",
cmake: "Cmake",
"cargo.toml": "Rust",
"go.mod": "GoMod",
"go.sum": "GoMod",
"requirements.txt": "Python",
"pyproject.toml": "Python",
pipfile: "Python",
"poetry.lock": "Poetry",
gemfile: "Gemfile",
rakefile: "Ruby",
"composer.json": "Php",
"build.gradle": "Gradle",
"pom.xml": "Maven",
"deno.json": "Deno",
"deno.jsonc": "Deno",
"vercel.json": "Vercel",
"netlify.toml": "Netlify",
".env": "Tune",
".env.local": "Tune",
".env.development": "Tune",
".env.production": "Tune",
".env.example": "Tune",
".editorconfig": "Editorconfig",
"robots.txt": "Robots",
"favicon.ico": "Favicon",
browserlist: "Browserlist",
".babelrc": "Babel",
"babel.config.js": "Babel",
"gulpfile.js": "Gulp",
"gruntfile.js": "Grunt",
"capacitor.config.json": "Capacitor",
"ionic.config.json": "Ionic",
"angular.json": "Angular",
".storybook": "Storybook",
"storybook.config.js": "Storybook",
"cypress.config.js": "Cypress",
"playwright.config.js": "Playwright",
"puppeteer.config.js": "Puppeteer",
"wrangler.toml": "Wrangler",
"firebase.json": "Firebase",
supabase: "Supabase",
terraform: "Terraform",
kubernetes: "Kubernetes",
".gitpod.yml": "Gitpod",
".devcontainer": "Vscode",
"travis.yml": "Travis",
"appveyor.yml": "Appveyor",
".circleci": "Circleci",
"renovate.json": "Renovate",
"dependabot.yml": "Dependabot",
"lerna.json": "Lerna",
"nx.json": "Nx",
},
fileExtensions: {
// Test files
"spec.ts": "TestTs",
"test.ts": "TestTs",
"spec.tsx": "TestJsx",
"test.tsx": "TestJsx",
"spec.js": "TestJs",
"test.js": "TestJs",
"spec.jsx": "TestJsx",
"test.jsx": "TestJsx",
// JavaScript/TypeScript
"js.map": "JavascriptMap",
"d.ts": "TypescriptDef",
ts: "Typescript",
tsx: "React_ts",
js: "Javascript",
jsx: "React",
mjs: "Javascript",
cjs: "Javascript",
// Web languages
html: "Html",
htm: "Html",
css: "Css",
scss: "Sass",
sass: "Sass",
less: "Less",
styl: "Stylus",
// Data formats
json: "Json",
jsonc: "Json",
xml: "Xml",
yml: "Yaml",
yaml: "Yaml",
toml: "Toml",
hjson: "Hjson",
// Documentation
md: "Markdown",
mdx: "Mdx",
tex: "Tex",
// Programming languages
py: "Python",
pyx: "Python",
pyw: "Python",
rs: "Rust",
go: "Go",
java: "Java",
kt: "Kotlin",
scala: "Scala",
php: "Php",
rb: "Ruby",
cs: "Csharp",
vb: "Visualstudio",
cpp: "Cpp",
cc: "Cpp",
cxx: "Cpp",
c: "C",
h: "H",
hpp: "Hpp",
swift: "Swift",
m: "ObjectiveC",
mm: "ObjectiveCpp",
dart: "Dart",
lua: "Lua",
pl: "Perl",
r: "R",
jl: "Julia",
hs: "Haskell",
elm: "Elm",
ml: "Ocaml",
clj: "Clojure",
cljs: "Clojure",
erl: "Erlang",
ex: "Elixir",
exs: "Elixir",
nim: "Nim",
zig: "Zig",
v: "Vlang",
odin: "Odin",
gleam: "Gleam",
grain: "Grain",
roc: "Rocket",
fs: "Fsharp",
// Shell scripts
sh: "Console",
bash: "Console",
zsh: "Console",
fish: "Console",
ps1: "Powershell",
// Config/build files
cfg: "Settings",
ini: "Settings",
conf: "Settings",
properties: "Settings",
// Media files
svg: "Svg",
png: "Image",
jpg: "Image",
jpeg: "Image",
gif: "Image",
webp: "Image",
bmp: "Image",
ico: "Favicon",
mp4: "Video",
mov: "Video",
avi: "Video",
webm: "Video",
mp3: "Audio",
wav: "Audio",
flac: "Audio",
// Archive files
zip: "Zip",
tar: "Zip",
gz: "Zip",
rar: "Zip",
"7z": "Zip",
// Document files
pdf: "Pdf",
doc: "Word",
docx: "Word",
ppt: "Powerpoint",
pptx: "Powerpoint",
xls: "Document",
xlsx: "Document",
// Database files
sql: "Database",
db: "Database",
sqlite: "Database",
// Other
env: "Tune",
log: "Log",
lock: "Lock",
key: "Key",
pem: "Certificate",
crt: "Certificate",
proto: "Proto",
graphql: "Graphql",
gql: "Graphql",
wasm: "Webassembly",
dockerfile: "Docker",
},
folderNames: {
// Source code
src: "FolderSrc",
source: "FolderSrc",
lib: "FolderLib",
libs: "FolderLib",
// Testing
test: "FolderTest",
tests: "FolderTest",
testing: "FolderTest",
spec: "FolderTest",
specs: "FolderTest",
__tests__: "FolderTest",
e2e: "FolderTest",
integration: "FolderTest",
unit: "FolderTest",
cypress: "FolderCypress",
// Dependencies
node_modules: "FolderNode",
vendor: "FolderPackages",
packages: "FolderPackages",
deps: "FolderPackages",
// Build/dist
build: "FolderBuildkite",
dist: "FolderDist",
out: "FolderDist",
output: "FolderDist",
target: "FolderTarget",
// Configuration
config: "FolderConfig",
configs: "FolderConfig",
configuration: "FolderConfig",
settings: "FolderConfig",
env: "FolderEnvironment",
environments: "FolderEnvironment",
// Docker
docker: "FolderDocker",
dockerfiles: "FolderDocker",
containers: "FolderDocker",
// Documentation
docs: "FolderDocs",
doc: "FolderDocs",
documentation: "FolderDocs",
readme: "FolderDocs",
// Public/assets
public: "FolderPublic",
static: "FolderPublic",
assets: "FolderImages",
images: "FolderImages",
img: "FolderImages",
icons: "FolderImages",
media: "FolderImages",
fonts: "FolderFont",
styles: "FolderCss",
stylesheets: "FolderCss",
css: "FolderCss",
sass: "FolderSass",
scss: "FolderSass",
less: "FolderLess",
// Scripts
scripts: "FolderScripts",
script: "FolderScripts",
tools: "FolderTools",
utils: "FolderUtils",
utilities: "FolderUtils",
helpers: "FolderHelper",
// Framework specific
components: "FolderComponents",
component: "FolderComponents",
views: "FolderViews",
view: "FolderViews",
layouts: "FolderLayout",
layout: "FolderLayout",
templates: "FolderTemplate",
template: "FolderTemplate",
hooks: "FolderHook",
hook: "FolderHook",
store: "FolderStore",
stores: "FolderStore",
state: "FolderNgrxStore",
reducers: "FolderReduxReducer",
reducer: "FolderReduxReducer",
services: "FolderApi",
service: "FolderApi",
api: "FolderApi",
apis: "FolderApi",
routes: "FolderRoutes",
route: "FolderRoutes",
routing: "FolderRoutes",
middleware: "FolderMiddleware",
middlewares: "FolderMiddleware",
controllers: "FolderController",
controller: "FolderController",
models: "FolderDatabase",
model: "FolderDatabase",
schemas: "FolderDatabase",
schema: "FolderDatabase",
migrations: "FolderDatabase",
migration: "FolderDatabase",
seeders: "FolderSeeders",
seeder: "FolderSeeders",
// TypeScript
types: "FolderTypescript",
typing: "FolderTypescript",
typings: "FolderTypescript",
"@types": "FolderTypescript",
interfaces: "FolderInterface",
interface: "FolderInterface",
// Mobile
android: "FolderAndroid",
ios: "FolderIos",
mobile: "FolderMobile",
flutter: "FolderFlutter",
// Infrastructure
kubernetes: "FolderKubernetes",
k8s: "FolderKubernetes",
terraform: "FolderTerraform",
aws: "FolderAws",
azure: "FolderAzurePipelines",
firebase: "FolderFirebase",
supabase: "FolderSupabase",
vercel: "FolderVercel",
netlify: "FolderNetlify",
// CI/CD
".github": "FolderGithub",
".gitlab": "FolderGitlab",
".circleci": "FolderCircleci",
ci: "FolderCi",
".ci": "FolderCi",
workflows: "FolderGhWorkflows",
// Git
".git": "FolderGit",
// Development tools
".vscode": "FolderVscode",
".idea": "FolderIntellij",
".cursor": "FolderCursor",
".devcontainer": "FolderContainer",
".storybook": "FolderStorybook",
// Localization
i18n: "FolderI18n",
locales: "FolderI18n",
locale: "FolderI18n",
lang: "FolderI18n",
languages: "FolderI18n",
// Other common patterns
temp: "FolderTemp",
tmp: "FolderTemp",
logs: "FolderLog",
log: "FolderLog",
backup: "FolderBackup",
backups: "FolderBackup",
examples: "FolderExamples",
example: "FolderExamples",
demo: "FolderExamples",
demos: "FolderExamples",
samples: "FolderExamples",
sample: "FolderExamples",
fixtures: "FolderTest",
mocks: "FolderMock",
mock: "FolderMock",
data: "FolderDatabase",
database: "FolderDatabase",
db: "FolderDatabase",
sql: "FolderDatabase",
prisma: "FolderPrisma",
drizzle: "FolderDrizzle",
// Security
security: "FolderSecure",
auth: "FolderSecure",
authentication: "FolderSecure",
authorization: "FolderSecure",
keys: "FolderKeys",
certs: "FolderKeys",
certificates: "FolderKeys",
// Content
content: "FolderContent",
posts: "FolderContent",
articles: "FolderContent",
blog: "FolderContent",
// Functions
functions: "FolderFunctions",
function: "FolderFunctions",
lambda: "FolderFunctions",
lambdas: "FolderFunctions",
serverless: "FolderServerless",
// Jobs/tasks
jobs: "FolderJob",
job: "FolderJob",
tasks: "FolderTasks",
task: "FolderTasks",
cron: "FolderTasks",
queue: "FolderQueue",
queues: "FolderQueue",
// Desktop platforms
desktop: "FolderDesktop",
windows: "FolderWindows",
macos: "FolderMacos",
linux: "FolderLinux",
},
defaults: {
file: "Document",
folder: "Folder",
folderOpen: "FolderOpen",
},
}
const toOpenVariant = (icon: IconName): IconName => {
if (!icon.startsWith("Folder")) return icon
if (icon.endsWith("_light")) {
// SAFETY: the icon generator writes an `Open` variant for every folder icon, light ones included.
return icon.replace("_light", "Open_light") as IconName
}
if (!icon.endsWith("Open")) {
// SAFETY: the icon generator writes an `Open` variant for every folder icon.
return (icon + "Open") as IconName
}
return icon
}
const basenameOf = (p: string) => p.split("\\").join("/").split("/").filter(Boolean).pop() ?? ""
const folderNameVariants = (name: string) => {
const n = name.toLowerCase()
return [n, `.${n}`, `_${n}`, `__${n}__`]
}
const dottedSuffixesDesc = (name: string) => {
const n = name.toLowerCase()
const idxs: number[] = []
for (let i = 0; i < n.length; i++) if (n[i] === ".") idxs.push(i)
const out = new Set<string>()
out.add(n) // allow exact whole-name "extensions" like "dockerfile"
for (const i of idxs) if (i + 1 < n.length) out.add(n.slice(i + 1))
return Array.from(out).sort((a, b) => b.length - a.length) // longest first
}
export function chooseIconName(path: string, type: "directory" | "file", expanded: boolean): IconName {
const base = basenameOf(path)
const baseLower = base.toLowerCase()
if (type === "directory") {
for (const cand of folderNameVariants(baseLower)) {
const icon = ICON_MAPS.folderNames[cand]
if (icon) return expanded ? toOpenVariant(icon) : icon
}
return expanded ? ICON_MAPS.defaults.folderOpen : ICON_MAPS.defaults.folder
}
const byName = ICON_MAPS.fileNames[baseLower]
if (byName) return byName
for (const ext of dottedSuffixesDesc(baseLower)) {
const icon = ICON_MAPS.fileExtensions[ext]
if (icon) return icon
}
return ICON_MAPS.defaults.file
}