The project template

Scope#

This page describes the beyond-web template, version 0.1.0: the template a project is created from in Beyond Projects. It is a minimal web application: one application package whose public module renders a standard custom element with its own styles, in a workspace that can hold more packages.

What the project contains#

The page it renders says "Hello, Beyond", a description, a Count button and "0 clicks", which increases when you press the button.

@project is a placeholder scope. Rename it in every package.json and in every import when you choose the name of your project.

{
	"packages": ["packages/app"]
}

The entry point defines the element once and adds it to the page. A preview imports the module and calls nothing, so this top-level code is what mounts the application; it is written so that running it twice changes nothing:

/**
 * The entry point of the public module `@project/app/main`, and the entry of the application.
 *
 * A preview imports this module, which runs the code below once: it defines the element of the application
 * and adds one to the page. Nothing calls an exported function for you. What this file exports is the public
 * API of the module; the other files of this directory are internal to it.
 */
import { Welcome } from './welcome';

export { Welcome };

customElements.get(Welcome.tag) ?? customElements.define(Welcome.tag, Welcome);
document.querySelector(Welcome.tag) ?? document.body.appendChild(document.createElement(Welcome.tag));

template.json is provenance, not configuration#

{
	"schema": "beyond-template/1",
	"name": "beyond-web",
	"version": "0.1.0",
	"description": "A minimal Beyond web application: one application package whose public module renders a custom element with its own styles, in a workspace that can hold more packages.",
	"compatibility": {
		"node": ">=22.21.1",
		"packages": { "name": "@beyond-js/packages", "validated": "0.0.1" },
		"moduleContract": { "name": "@beyond-js/artifact-api", "validated": "0.2.0" },
		"runtime": { "name": "@beyond-js/kernel", "module": "@beyond-js/kernel/bundle", "validated": "0.1.14" },
		"browser": "Import maps, constructable stylesheets and custom elements. Validated with Chrome 153."
	},
	"notes": "This file records which template version seeded the project. It is provenance, not configuration: nothing reads it to build or serve the application. Keep it when you change the project. A later template version never rewrites an existing project."
}

• Nothing reads this file to build or serve the application.
• It records which template version seeded the project and what that version was verified with. Keep it, and do not edit it.
• A later template version never rewrites an existing project. Beyond Projects records the same fact on its side: see the template version is recorded.

The element and its styles#

The Packages version this template was verified with compiles TypeScript modules only. It produces no Beyond Widgets metadata and no style artifact. So the seed is built from web standards:

• The interface is a standard custom element that renders into its own shadow root.
• Its styles are a constructable stylesheet created in a TypeScript file and adopted by the shadow root, so the styles travel inside the compiled module and nothing else has to be loaded.

Serve and preview it#

Prerequisites:

• Node.js 22.21.1 or later.
• A Beyond toolchain installation that provides the beyond command, with Beyond Packages 0.0.1. It is not published in a public registry: use the installation that your Beyond Workspace environment or your team provides. Nothing is installed inside the project, and it needs no npm install.
• The origin of a Beyond module delivery service in BEYOND_CDN_ORIGIN. Your development server serves the packages of the workspace; everything else, including the Beyond runtime that every compiled module imports (@beyond-js/kernel/bundle), comes from that origin at its exact version. Without the variable, the preview says which modules have no address instead of guessing one, and the page does not load.

# From the project directory. The toolchain that provides `beyond` is not in a public registry:
# use the installation your Beyond Workspace environment or your team provides.
BEYOND_SERVICE_EXTENSIONS=@beyond-js/packages/development \
BEYOND_CDN_ORIGIN=https://<your module delivery origin> \
beyond run

Expected outcome: beyond: development server started, the workspace directory and an endpoint line with a local address. The port changes between starts. The server compiles on request and watches your sources; leave it running, and stop it with Ctrl+C.

BEYOND_SERVICE_EXTENSIONS adds the development routes, the preview among them, to the server that this command starts. If a server for this project is already running without it, stop that one first.

Beyond Workspace runs this same development server for the project inside your environment and shows its preview in a panel. What was verified for this template version is running it yourself with the command above; no Workspace preview has loaded in a browser end to end.

An edit shows after a reload#

Saving a source file rebuilds the modules it affects. Load the preview again to see the change. A project generated from this template does not update a page that is already running, and the state of the page is lost on reload, as in any page. Updating the running page needs a development runtime that this template version does not include.

A source error never shows stale output: entry.json and /state report the compiler diagnostic, and the module answers with an error until you correct the file.

What was verified, and what is not available#

Next action#

Publish a module and add a sibling package.