La plantilla del proyecto

Alcance#

Esta página describe la plantilla beyond-web, versión 0.1.0: la plantilla a partir de la cual se crea un proyecto en Beyond Projects. Es una aplicación web mínima: un paquete de aplicación cuyo módulo público renderiza un custom element estándar con sus propios estilos, en un workspace que puede contener más paquetes.

Qué contiene el proyecto#

La página que renderiza dice «Hello, Beyond», una descripción, un botón Count y «0 clicks», que aumenta cuando presionas el botón. Esos textos están en inglés en la plantilla.

@project es un scope de ejemplo. Cámbialo en cada package.json y en cada import cuando elijas el nombre de tu proyecto.

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

El punto de entrada define el elemento una vez y lo agrega a la página. Una vista previa importa el módulo y no llama a nada, así que este código de nivel superior es lo que monta la aplicación; está escrito de modo que ejecutarlo dos veces no cambie nada:

/**
 * 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 es procedencia, no configuración#

{
	"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."
}

• Nada lee este archivo para compilar o servir la aplicación.
• Registra qué versión de la plantilla originó el proyecto y con qué se verificó esa versión. Consérvalo, y no lo edites.
• Una versión posterior de la plantilla nunca reescribe un proyecto existente. Beyond Projects registra el mismo hecho de su lado: consulta la versión de la plantilla queda registrada.

El elemento y sus estilos#

La versión de Packages con la que se verificó esta plantilla compila solo módulos TypeScript. No produce metadatos de Beyond Widgets ni un artefacto de estilos. Por eso la base está hecha con estándares web:

• La interfaz es un custom element estándar que renderiza en su propio shadow root.
• Sus estilos son una hoja de estilos construible creada en un archivo TypeScript y adoptada por el shadow root, así que los estilos viajan dentro del módulo compilado y no hay que cargar nada más.

Servirlo y previsualizarlo#

Requisitos:

• Node.js 22.21.1 o posterior.
• Una instalación de las herramientas de Beyond que provea el comando beyond, con Beyond Packages 0.0.1. No está publicada en un registro público: usa la instalación que provea tu entorno de Beyond Workspace o tu equipo. No se instala nada dentro del proyecto, y no necesita npm install.
• El origen de un servicio de entrega de módulos de Beyond en BEYOND_CDN_ORIGIN. Tu servidor de desarrollo sirve los paquetes del workspace; todo lo demás, incluido el runtime de Beyond que importa cada módulo compilado (@beyond-js/kernel/bundle), viene de ese origen en su versión exacta. Sin la variable, la vista previa dice qué módulos no tienen dirección en vez de adivinar una, y la página no carga.

# 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

Resultado esperado: beyond: development server started, el directorio del workspace y una línea endpoint con una dirección local. El puerto cambia entre un inicio y otro. El servidor compila a pedido y observa tu código; déjalo en ejecución, y detenlo con Ctrl+C.

BEYOND_SERVICE_EXTENSIONS agrega las rutas de desarrollo, entre ellas la vista previa, al servidor que inicia este comando. Si ya hay un servidor de este proyecto en ejecución sin ella, detén ese primero.

Beyond Workspace ejecuta este mismo servidor de desarrollo para el proyecto dentro de tu entorno y muestra su vista previa en un panel. Lo que se verificó para esta versión de la plantilla es ejecutarlo tú con el comando de arriba; ninguna vista previa de Workspace cargó en un navegador de punta a punta.

Una edición se ve después de recargar#

Guardar un archivo de código recompila los módulos a los que afecta. Carga de nuevo la vista previa para ver el cambio. Un proyecto generado a partir de esta plantilla no actualiza una página que ya está en ejecución, y el estado de la página se pierde al recargar, como en cualquier página. Actualizar la página en ejecución necesita un runtime de desarrollo que esta versión de la plantilla no incluye.

Un error en el código nunca muestra una salida vieja: entry.json y /state informan el diagnóstico del compilador, y el módulo responde con un error hasta que corrijas el archivo.

Qué se verificó, y qué no está disponible#

Siguiente acción#

Publica un módulo y agrega un paquete hermano.