@blockbite/astro · BlockBite

@blockbite/astro is a thin ESM integration for an ordinary Astro project. Astro owns rendering, routing, assets, CSS and builds. The package adds island declarations, generated prop types and page-content validation.

The package is under development and is not published on npm. Use Desktop’s setup archive when preparing an existing project.

Register the integration

Add blockbite() alongside your existing integrations in astro.config.mjs:

import { defineConfig } from 'astro/config';
import blockbite from '@blockbite/astro';

export default defineConfig({
  integrations: [blockbite()],
});

blockbite() takes no options. It validates island declarations, watches their files and generates IslandProps types through Astro. Optional project settings belong in blockbite.config.json.

Core imports

Import	Use
`@blockbite/astro`	Default `blockbite()` integration and `loadBlockbiteConfig(projectRoot)`
`@blockbite/astro/islands`	`loadIslands()` and generated `IslandProps<'family/variant'>`
`@blockbite/astro/content`	`createPageSchema()` to validate JSON page sections
`@blockbite/astro/markdown-inline`	Native component for declared inline Markdown fields
`@blockbite/astro/image`	Optional native component for managed image composition
`@blockbite/astro/images`	Portable image facts, recipes and geometry
`@blockbite/astro/svg`	Native component for approved SVG-library icons
`@blockbite/astro/guidance`	Versioned project-authoring guidance

loadIslands() accepts an absolute file URL for the islands directory. loadBlockbiteConfig() accepts an absolute file URL for the project root. Reading configuration does not create content or write project files.

Islands and page content

An editable section lives in src/islands/<family>/<variant>/Island.astro, with its contract in fields.yaml. Page JSON names family/variant and supplies the field values. The native route imports the components and binds those values explicitly.

Island folders: declare and type a section.
Page content: wire a collection and route.
Island file reference: exact properties, limits and additional package exports.
Image editing: image source bindings and crops.

Ordinary Astro components and Markdown articles can stay native without becoming BlockBite islands. A BlockBite island is an editable section; it does not by itself require browser hydration.

Agent context

With the package installed, run these from your project using its local CLI (the example uses npm):

npx --no-install blockbite context --list
npx --no-install blockbite context
npx --no-install blockbite context --check

--list shows available guidance, the plain command reads the default context, and --check checks the project’s guidance reference. See agentic building for the workflow.

Editing and delivery

The package also exposes bounded source-analysis and editing helpers consumed by Desktop. Unsupported or ambiguous source can remain read-only. Check saved changes in Native Play and the normal Astro build.

Native Astro authoring is the active workflow. WordPress/Twig exports are retained legacy interfaces; EmDash has a bounded offline pilot. See integrations for their current scope.