Getting Started

The recommended starting point is the official template repo:

pnpx degit svebcomponents/template my-project
cd my-project
pnpm install
pnpm dev

The template gives you a small pnpm workspace:

• components/example-component: a Svelte custom element package
• apps/svelte-kit: a SvelteKit app that consumes the custom element
• configs/*: shared linting, formatting, and TypeScript config packages

Example Component

Take a look at the example component in components/example-component/src/ExampleComponent.svelte:

<script lang="ts">
  let {
    increments = 1,
  }: {
    increments: number;
  } = $props();

  let count = $state(0);
</script>

<button onclick={() => (count += increments)}>
  add {increments} to {count}
</button>

If you know Svelte 5, there is nothing unfamiliar here. It is a regular Svelte component with typed props.

increments: number;

The type annotation is enough information for @svebcomponents/auto-options to generate the prop metadata Svelte needs to convert the increments attribute from a string to a number.

Component Entrypoint

The package entrypoint imports the Svelte component and registers the generated custom element constructor:

import ExampleComponent from "./ExampleComponent.svelte";

export default ExampleComponent;

if (!customElements.get("example-component") && "element" in ExampleComponent) {
  customElements.define(
    "example-component",
    ExampleComponent.element as CustomElementConstructor,
  );
}

Note

When Svelte compiles a component as a custom element, it exposes the constructor as Component.element.

Note

Svelte can register a custom element through <svelte:options>. Svebcomponents keeps registration in the entrypoint instead, so you can tailor it to your needs.

Package Exports

The exports field of your component’s package.json tells consumers where the custom element lives:

{
  "exports": {
    ".": {
      "types": "./dist/client/index.d.ts",
      "svelte": "./dist/client-svelte/index.js",
      "default": "./dist/client/index.js"
    }
  }
}

This declaration also doubles as build configuration. The svebcomponents CLI maps dist/client/index.js back to src/index.ts and builds that entrypoint. It also creates a lighter Svelte-aware build at dist/client-svelte/index.js, which Svelte tooling can select through the svelte condition.

From the component package, run:

pnpm build

See Build for the complete inference rules, multiple entrypoints, and manual configuration.

Using the Component

You use the generated custom element just like any other web component:

<script lang="ts">
  import "@svebcomponents/example-component";
</script>

<example-component increments={5}></example-component>

Caution

Svelte 5 sets attributes as JavaScript properties under certain conditions. Therefore, you should use JavaScript expressions for non-string values when consuming custom elements from Svelte.

In the example above, increments={5} passes the number 5, while writing increments="5" passes the string "5" from Svelte’s JavaScript side. This bypasses the custom element attribute converter.

See sveltejs/svelte#12624.

What Next?

• Read Build to understand entrypoints and package export inference.
• Read Auto-options to understand prop and attribute conversion.
• Read SSR when you want to explore server rendering.