> For the complete documentation index, see [llms.txt](https://beamline.gitbook.io/beamline-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://beamline.gitbook.io/beamline-docs/getting-started/start-here.md). # Start here Local code in your repo, your own style and no Beamline runtime dependency: source, package archives, rights, install options and the kit's contents. > The original of this page is on beamline.io: [beamline.io/docs/start-here](https://beamline.io/docs/start-here). > Beamline code and your custom style files stay in your repo; your app has no Beamline runtime dependency. This documentation ships with the complete system (START-HERE.md in the kit). Use [local kit tools](https://beamline.io/docs/install) or [connect an agent](https://beamline.io/connect) to install parts. **The code lives in your repo; your app never depends on Beamline servers at runtime.** You own your end products and changes under the [licence](https://beamline.io/docs/licence). **Build your own style from any look** with public tokens, your fonts, radii, spacing density and motion; it is not limited to changing colours. React 19 components and complete screens for SaaS tools, trading interfaces, dashboards and AI-agent products, in dark and light. Shared tokens and one stylesheet, with starting looks or a custom style you build. You get the editable source of everything, installable packages built from that same source, and a reference application that runs on it. ## Your files stay with your app * **Editable components:** `src/ui/beamline` by default. Change any component directly. * **Compiled parts:** local archives in `.beamline/packages/`. Commit the root `.beamline/` folder with the app; its package manifest and lockfile refer to those files. * **Your custom style:** editable files in `src/styles/beamline`. Source and package upgrades leave this directory alone. Start from any look, change public tokens for every surface, text and chart colour, choose radii, roundness, density and motion, and install your own fonts explicitly. Use the local studio when the bundle includes it, or have your agent use the local `style` CLI: `create`, `set`, `parameter`, `export`, `add`. For individual parts, use `className`, `data-slot` and `data-state`. Component CSS sits in `@layer components`, below normal unlayered app CSS; the usual cascade still applies. Your own parts can use the same surface role classes. A look changes typography, icon weight, surfaces and the page without changing the size scale; different fonts can change text wrapping. [Customise](https://beamline.io/docs/customize) gives the supported tokens and commands. The hosted MCP server helps an agent find and install parts. You can also install with local kit tools. Your running app never calls Beamline's servers, and received versions remain licensed to you if Beamline stops publishing. Your app's own backend and other dependencies remain yours to maintain. The underlying Beamline code stays under its licence, including changes that contain it; paid packs cannot be resold or redistributed on their own or as a UI kit. The free [GitHub sample](https://github.com/dprvda/beamline) is MIT. See [Install](https://beamline.io/docs/install) and [Upgrade](https://beamline.io/docs/upgrade). ## What is in this folder | folder | what it is | | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `release.json`, `packages/` | The release descriptor and its verified npm archives: selected `@beamline/*` packages, compiled ES modules and type declarations. The installer chooses the required archives. | | `source/ui/` | The editable TypeScript and CSS the package is built from: components, blocks (whole screens), hooks, helpers, styles, and each entry's examples (`demo.tsx`). | | `reference-app/` | A complete React 19 + Vite application using the package: navigation, connected screens, data adapters and a brand change. The complete bundle has five screens; a standalone pack keeps the screens of the blocks it carries (a pack without blocks has no app and starts from `examples/`). Start here to see how the pieces fit. | | `examples/` | Smaller focused apps: Beamline added to an existing app without touching its styles (`embed-in-existing-app`), and editable source with Tailwind (`source-app`, when this bundle carries its elements). | | `catalog/catalog.json`, `CAPABILITIES.md` | The machine-readable catalog and complete element menu: what each part is for, imports, props and keyboard. The finder reads the same catalog offline. | | `previews/` (when included) | A gallery snapshot matched to this release. `MANIFEST.json` records whether this bundle carries previews. | | `docs/` | Install, upgrade, customise, data integration, dependencies and licences, known limitations, changelog, conventions and design language. | | `tools/beamline.mjs` | Installs compiled packages or full editable source, including the base, and manages source upgrades while preserving edits. | | `AGENTS.md`, `agents/` | Instructions and a small skill for coding agents (Claude Code, Codex and others) working with this system. | | `LICENSE.md`, `THIRD-PARTY-LICENSES.md`, `NOTICE` | The licence for Beamline itself, and every third-party package it can bring in with its licence and obligations. | | `MANIFEST.json` | Exact version, source revision, entry list and a checksum for every file in this bundle. | ## Run the reference app (5 minutes) Needs Node 20 or newer. ```bash cd reference-app npm install npm run dev ``` Open the address it prints. The screens run on demonstration data that is labelled as such on screen; nothing calls an external service. `reference-app/README.md` shows where each screen's data comes in and where your backend goes. ## Use it in your app Two supported ways, both described step by step in [docs/INSTALL.md](https://beamline.io/docs/install): 1. **Compiled packages**: `tools/beamline.mjs install --release release.json` installs the selected `@beamline/*` packages, runtime, foundation, looks and fonts. The generated stylesheet lands in `src/styles/beamline/beamline.css`. No Tailwind needed for Beamline. 2. **Full editable source**: `tools/beamline.mjs source --release release.json --install` puts components, blocks, runtime, foundation, helpers, selected looks and local fonts in `src/ui/beamline`. Every Beamline file your app uses can be source in your repo. There are no `@beamline/*` dependencies; third-party libraries stay ordinary npm packages. Enable Tailwind v4 and import the managed `styles/beamline.css`. Building and running the installed app needs no connection to beamline.io. Managed upgrades preserve edits to base files as well as components. The source CLI is also used by the agent installer; MCP accepts `source: true`. The shadcn registry copies the base as source items too (font bytes are embedded in local CSS). Existing source installs retain their packaged base until explicitly migrated; see [docs/INSTALL.md](https://beamline.io/docs/install). The free runtime/foundation/Prism sample is MIT-licensed, selected fonts carry SIL OFL 1.1, and paid parts retain the Beamline licence ([LICENSE.md](https://beamline.io/docs/licence), section 4). From the app folder, using the absolute path to your extracted kit: ```bash node /path/to/release/tools/beamline.mjs install order-book --release /path/to/release/release.json --preset prism ``` For full editable source, use `source order-book` with `--install` instead of `install order-book`. Original 0.1 archives use their own matching instructions; see the legacy section of the install guide. Then set your brand colour ([docs/CUSTOMIZE.md](https://beamline.io/docs/customize)) and connect your data ([docs/DATA-INTEGRATION.md](https://beamline.io/docs/data-integration)). ## Find the right element Read `CAPABILITIES.md` or search by job ("pick a date range", "show an order book", "ask for approval") with `node /path/to/release/agents/skills/beamline-ui/scripts/find.mjs --app /path/to/app `. Every entry says what to use instead when it is the wrong fit. ## Before you rely on it Read [docs/LIMITATIONS.md](https://beamline.io/docs/limitations): it lists what is demonstration-only, which layouts are verified, which browsers were exercised, and where your own backend has to do the work. The UI never pretends an external action succeeded; your handlers decide what the screens show. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://beamline.gitbook.io/beamline-docs/getting-started/start-here.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.