BlockBite docs

Import an existing project

Connect an existing Astro project to BlockBite Desktop while keeping its native structure.

@blockbite/astro adds a thin connection to BlockBite Desktop and Siteboards. Your project keeps Astro’s renderer, routes, assets and existing integrations. This guide is for an existing Astro project. Move sites built with another framework to Astro before preparing them for BlockBite.

1. Back up your project

Make a backup or commit your current work to Git, including untracked files. Desktop edits the folder you select directly. If you work in a copy, changes are not synchronized back to the original.

2. Prepare the project

Install the Astro layer

The current development package is not published on npm. In Desktop, choose Open existing project, select your project folder and choose Save setup package. This writes .blockbite/packages/blockbite-astro.tgz inside that folder without installing or running it.

Use your existing package manager and keep its lockfile:

# npm
npm install --ignore-scripts ./.blockbite/packages/blockbite-astro.tgz

# pnpm
pnpm add --ignore-scripts ./.blockbite/packages/blockbite-astro.tgz

# Yarn 1
yarn add --ignore-scripts @blockbite/astro@file:./.blockbite/packages/blockbite-astro.tgz

# Yarn 2+
YARN_ENABLE_SCRIPTS=false yarn add @blockbite/astro@file:./.blockbite/packages/blockbite-astro.tgz

Review any dependency build requirements separately. Desktop currently supports Astro ^7.3.8, with 7.3.8 verified.

Register the integration

Add the import and blockbite() to your existing Astro configuration, preserving all other options and integrations:

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

export default defineConfig({
  integrations: [
    blockbite(),
    // Keep your existing integrations here.
  ],
});

Prepare editable islands

  • Use Tailwind CSS in islands intended for visual editing, through Astro’s native Tailwind setup. Unrelated project styles can stay as they are.
  • Keep existing .astro and .tsx components and their framework integrations. Visual editing applies to supported Astro source and explicit content bindings; framework component internals and dynamic expressions can remain read-only.
  • Declare editable sections as src/islands/<family>/<variant>/Island.astro with fields.yaml, then connect them to JSON page content through explicit native component calls. Follow island folders and page content.

Run the project’s relevant checks and Astro build before opening the visual editor. The Copy agent prompt button in Desktop can help an agent prepare these changes while preserving your existing site.

3. Add the project in Desktop

Choose the prepared project folder, select Check again if it is already selected, then Add project. Configuration registration is verified when preview starts. Choosing or adding a folder does not run its code.

Start Native Play only after reviewing and trusting the project. Check a saved text edit and the project’s normal Astro build before handing it to an editor.