@collagejs/svelte

Svelte v5 integration for the CollageJS micro-frontend library

Online Documentation

This is the official Svelte framework adatper for CollageJS used to:

1. Create CorePiece objects from Svelte components.
2. Consume CorePiece objects (built with any framework or library) in Svelte projects.

Quickstart - Creating Pieces

Assuming you have a Vite-powered Svelte project:

1. Install packages:

   npm install @collagejs/svelte @collagejs/vite-css

2. Configure the plug-in:

   ...
   import { cjsCssPlugin } from '@collagejs/vite-css';
   
   export default defineConfig({
       plugins: [..., cjsCssPlugin({
           serverPort: 6101,
           aim: false
       })],
       ...
   });

3. Add src/piece.ts to create and export a piece factory function:

   import { buildPiece } from '@collagejs/svelte';
   import MyComponent from './lib/MyComponent.svelte';
   // Optional CSS algorithm if you're not doing something else like CSS in JS.
   import { CssFactory } from '@collagejs/vite-css/ex';
   
   const css = new CssFactory(import.meta.url);
   
   export function myComponentFactory() {
       const piece = buildPiece(MyComponent /*, options */);
       const { mount, relocate } = css.instantiate();
       return {
           ...piece,
           mount: [mount, piece.mount],
           relocate: [relocate, piece.relocate],
       };
   }

Done. Import this factory function from outside this project using import maps, or distributing this code as an NPM package, etc. The importer can mount the piece using a framework adapter or the core mountPiece function from @collagejs/core.

Quickstart - Consuming Pieces

To consume or mount pieces is as simple as adding a Svelte component. The difficult part is setting up the source of the piece.

This is supposed to be a quick start, so let's go for the quickest (not recommended for production):

1. Somewhere in your code, import the piece module and get to the factory function:

   const moduleUrl = 'http://localhost:6101/piece.js',
   const { myComponentFactory } = await import(/* @vite-ignore*/ moduleUrl);

2. During component initialization (the component that will mount the piece), create a piece instance with the factory function:

   const corePiece = myComponentFactory();

3. Import and use the Piece component:

   import { Piece, piece } from '@collagejs/svelte';

   <Piece {...piece(corePiece)} />

This is it, in its most basic form.