Develop with Beyond
How a Beyond project is organized for a developer. A workspace lists packages, a package publishes public modules, and modules reach each other only by bare specifier. What you can run today, and what you cannot.
- Availability: Experimental
- Evidence: Recorded run
- Explanation
The model in one minute
A Beyond project is a workspace: one directory whose beyond.json lists its packages.
| Word | What it is | Declared in |
|---|---|---|
| Workspace | The project directory. A package that is not listed does not exist for Beyond. There are no globs, and npm workspaces are not used | beyond.json |
| Package | A directory with a name, an exact version, its public modules, its dependencies and its bundler | package.json |
| Public module | What other code imports by a bare specifier such as @project/app/main. A module.json declares it, with its platforms, its entry point and, for a widget, its element; a package exports entry is an alternative, and the way a package publishes a stylesheet with no code |
module.json, package identity/discovery/bundler settings; optional package exports |
| Internal file | Every other file of a module directory. Internal files import each other with relative paths, and nothing outside the module can import them. A file is not public because it exists | Nothing: it is the default |
The rule that holds the model together: code in one public module reaches another public module only by its bare specifier, never by a relative path, even when both are in the same workspace. Beyond compiles each public module into its own artifact and keeps that bare import in the output. A relative path across the boundary would copy the other module's source into yours.
What you can do today
- Read what a new project contains: The project template.
- Publish a module from a package, and share code between packages without breaking the boundary: Packages and public modules.
- Build a page from one module with its stylesheet, an asset and source maps, and change its CSS while it is open: Your first UI.
- Compile CSS, SCSS and Tailwind, share a stylesheet across the widgets of a package, and see what a failed stylesheet does: Styles.
- Build a React 19, Vue or Svelte widget with a styled dependency, and update it in place: Author a Beyond widget.
- See how compiled public modules are requested over HTTP, with the same address on a development server and on the CDN: URLs and identities.
What is not available
Extend Beyond
Write a widget without a view framework, or an adapter for another one: Integrate a view framework. Put a widget in a page built without Beyond: Embed a widget in an existing page. Run public modules on a server of your own: Create a modular execution environment. Teach the compiler a new source format: Create a bundler or a processor.
- The project template — What a project created from the beyond-web template 0.1.0 contains, how to serve and preview it with the Beyond command line, what template.json records, and the limits of this template version.
- Packages and public modules — How a package publishes a module in a project created from the beyond-web template, how to add a public module and a sibling package whose bare import is preserved, and how to check each change.
- Your first UI — Build a web page from one public module declared by a module.json, with its own stylesheet, a declared SVG asset and source maps; serve it with the Beyond command line, see it in a browser, change its CSS without reloading, and request its production output.
- Styles — How the stylesheets of a public module are compiled and delivered by Beyond Packages: CSS and SCSS with partials and a theme, Tailwind scanning only the sources a module declares, selecting another module's stylesheet with .css, the shared global stylesheet of a package, what a failed stylesheet does, and how a change reaches a page.
- Author a Beyond widget — Build a React 19 widget declared by its module.json, give it a Tailwind stylesheet and a styled public dependency of another package, see it mount in its own shadow root, change its code and its CSS without reloading, and do the same with a Vue or a Svelte view.
- Integrate a view framework — What a widget controller does for a view framework, shown by a widget written without one, in plain HTML, with a client controller and a server controller; then how the supplied React 19, Vue and Svelte adapters do the same, and what a new adapter must own.
- Embed a widget in an existing page — Put a Beyond widget into a page that was not built with Beyond, from another origin, with the same dependency and shared styles it has in its own application: the import map, the registration, two instances, and what happens on removal and reinsertion.
- Create a modular execution environment — What a host that executes Beyond public modules must do, shown by BEE Node and Deno: resolving bare identities through a development service or a release's resolution, a Node host that renders widgets on the server, the difference between packaged and composed artifacts, and what a host may and may not expect from updates.
- Create a bundler or a processor — The two ways to teach Beyond Packages a new way of compiling a public module, shown with the bundlers it ships: a bundler written against the core module contract, a bundler composed from processors with the SDK, and a reusable processor with its inputs, outputs, diagnostics, dependencies and cleanup.
- Test a package — Write ordinary test files for a Beyond package and run them with beyond test, Node's own test runner over the compiled public modules; locate a failure in the TypeScript source, narrow a run, mock a public module, assert asynchronous behavior, read coverage on the sources and attach a debugger.
- The beyond test reference — The exact contract of beyond test: the command line, how test files are collected, what the test processes receive, the build gate, module mocks, coverage, the file identities of served modules, the module manifest override, the messages and the exit codes.
Looking for the place where projects are created and shared with a team? See Beyond Workspace and Projects.