Build a first site

Begin with a basic blocklet, then add only the files Web Device needs to render a page. The file tree, checks, build, and browser result below were verified together with arc 2.0.0-beta.25.

1. Create the blocklet directory

arc blocklet init ./my-site --recipe basic --name my-site
cd ./my-site

The command creates blocklet.yaml and prints the generated DID. Keep that file; this local identity does not require you to create, sign in to, or deploy a DID Space.

Confirm the generated id:

grep -E '^id:' blocklet.yaml

When this guide created the blocklet with --name my-site, the verified result was id: my-site. The site value in the next step must use the value you see in your own file.

Create the directories used by the remaining files:

mkdir -p .route .web/components/hello pages/index

2. Declare the Web route

Use any text editor to create .route/web. Use the id you just read from blocklet.yaml as site:

site: my-site
path: /
source: .
handler: web

This declaration matters. Without it, a direct blocklet URL looks for .aup/app.aup or .aup/app.json, which is an AUP app entry rather than this static Web Device entry.

3. Add site configuration

Use any text editor to create .web/site.yaml:

domain: my-site.local
locale: en
render-mode: static
seo:
  og-site-name: My Site
  description: A minimal local Web Device site.

domain is site configuration. This command sequence still uses a local URL; it does not deploy to that domain.

4. Add one site component

Use any text editor to create .web/components/hello/manifest.json:

{
  "name": "hello",
  "description": "A minimal local component.",
  "props": {
    "title": { "type": "string" },
    "text": { "type": "string" }
  }
}

Create .web/components/hello/render.js:

export function render(ctx) {
  const { props, escapeHtml } = ctx;
  return {
    html: `<main><h1>${escapeHtml(props.title || "")}</h1><p>${escapeHtml(props.text || "")}</p></main>`,
  };
}

Create .web/components/hello/style.css:

main {
  max-width: 42rem;
  margin: 4rem auto;
  font-family: system-ui, sans-serif;
}

For a custom component that does not overlay a theme component, this version's checker requires manifest.json, render.js, and style.css in the same directory. If style.css is absent, arc dsl lint reports missing_web_component_file.

5. Add the home-page layout

Create pages/index/layout.aup:

page index {
  hello main title="Hello, Web Device" text="This page is rendered by a local blocklet."
}

hello is the component you just created. The page contains one component because this guide is only proving the route, AUP layout, and site component work together. It is not a complete content-site or theme template.

Continue to Run, check, and inspect to validate these files and open the rendered page.