upstream-affine/blocksuite/docs-site/guide/quick-start.md

Quick Start

For a swift start with BlockSuite, you can either kick off with ready-made examples for popular frameworks, or simply install the core packages to integrate it into your project.

::: info If this is your first time using BlockSuite, referring to the overview section may be helpful. :::

Bootstrap Project

BlockSuite works with all common frameworks, you can start from these examples that basically builds a TodoMVC-like note app based on BlockSuite.

Framework	Link	Maintaining
Vanilla	vanilla-indexeddb	✅
Next	react-basic-next	✅
React	react-basic	✅
Vue	vue-basic	✅
Angular	angular-basic	✅
Preact	preact-basic	✅
Svelte	svelte-basic	✅
Solid	solid-basic	✅

Init From Scratch

To use BlockSuite in your existing project, simply install these core packages:

yarn install \
  @blocksuite/presets@canary \
  @blocksuite/blocks@canary \
  @blocksuite/store@canary

Key takeaways in the snippet above:

• The @blocksuite/presets package contains the prebuilt editors and opt-in additional UI components.
• To work with the BlockSuite document model and first-party blocks, the @blocksuite/store and @blocksuite/blocks packages are required.
• The BlockSuite canary versions are released daily based on the master branch, which is also used in production in AFFiNE.

Then you can use the prebuilt PageEditor out of the box, with an initialized doc instance attached as its document model:

::: code-sandbox {coderHeight=420 previewHeight=300}

import { createEmptyDoc, PageEditor } from '@blocksuite/presets';
import { Text } from '@blocksuite/store';

(async () => {
  // Init editor with default block tree
  const doc = createEmptyDoc().init();
  const editor = new PageEditor();
  editor.doc = doc;
  document.body.appendChild(editor);

  // Update block node with some initial text content
  const paragraphs = doc.getBlockByFlavour('affine:paragraph');
  const paragraph = paragraphs[0];
  doc.updateBlock(paragraph, { text: new Text('Hello World!') });
})();

:::

The PageEditor here is a standard web component that can also be reused with <page-editor> HTML tag. Another EdgelessEditor also works similarly - simply attach the editor with a doc and you are all set.

For the doc.getBlockByFlavour and doc.updateBlock APIs used here, please see the introduction about block tree basics for further details.

As the next step, you can choose to:

• Explore how BlockSuite break down editors into different component types. Taking a look at the list of BlockSuite components may also be helpful.
• Try collaborative editing following the steps.
• Learn about basic concepts in BlockSuite framework that are used throughout the development of editors.

Note that BlockSuite is still under rapid development. For any questions or feedback, feel free to let us know!