Svelte Lib Helpers is a utility package designed to streamline various tasks when developing Svelte libraries. It offers a set of subcommands that simplify the process of managing exports, documentation, package distribution, and more.
Install Svelte Lib Helpers as a development dependency using npm/pnpm/yarn/bun:
pnpm i -D svelte-lib-helpers
Svelte Lib Helpers provides the following subcommands to enhance your Svelte library development workflow:
The exports
subcommand simplifies updating your package.json by adding or updating all Svelte files in src/lib. This enables efficient imports of individual components and reducing package size for developers.
Add the following to your package.json scripts section:
"gen:exports": "svelte-lib-helpers exports",
Copies your project’s package.json to the dist directory, allowing for seamless distribution of your library.
Add the following to your package.json scripts section:
"copy:package": "svelte-lib-helpers package",
Generates component documentation for all Svelte files within the src/lib directory.
You need to set “homepage” value in your package.json
file.
"homepage": "https://flowbite-svelte.com/",
The docs
and docsFromProps
subcommands work for Svelte 4 structure. From the following props structure:
export let color: 'primary' | 'blue' | 'gray' | 'green' | 'red' | 'yellow' | 'pink' | 'purple' | 'white' | 'custom' | undefined = 'primary';
export let bg: string = 'text-gray-300';
export let customColor: string = '';
export let size: string | number = '8';
To:
<!--
@component
[Go to docs](https://github.com/shinokada/svelte-lib-helpers#readme)
## Props
@prop export let color: 'primary' | 'blue' | 'gray' | 'green' | 'red' | 'yellow' | 'pink' | 'purple' | 'white' | 'custom' | undefined = 'primary';
@prop export let bg: string = 'text-gray-300';
@prop export let customColor: string = '';
@prop export let size: string | number = '8';
-->
Or from the following structure:
interface $$Props extends ComponentProps<TransitionFrame> {
dismissable?: boolean;
defaultClass?: string;
}
export let dismissable: $$Props['dismissable'] = false;
export let defaultClass: $$Props['defaultClass'] = 'p-4 gap-3 text-sm';
To:
<!--
@component
[Go to docs](https://github.com/shinokada/svelte-lib-helpers#readme)
## Props
@prop export let dismissable: boolean = false
@prop export let defaultClass: string = 'p-4 gap-3 text-sm'
-->
The subcommand docs5
extracts prop definitions from your Svelte 5 components to generate documentation. It focuses on the prop destructuring syntax specific to Svelte 5 and creates a simple list of props with their default values.
Your Svelte 5 component must use the $props() syntax for prop destructuring. The command supports various prop type annotations, including custom types.
The command searches for the prop destructuring pattern in your Svelte files: javascriptCopylet { … }: SomePropsType = $props()
It extracts all props defined within the curly braces. The extracted props are used to generate documentation comments in the Svelte file.
The command generates a comment block in your Svelte file with the following structure.
From the following props structure:
let {
children: Snippet,
footerType: 'sitemap' | 'default' | 'logo' | 'socialmedia' | undefined = 'default',
class: string | undefined = '',
...attributes
}: Props = $props();
To:
<!--
@component
[Go to docs](https://github.com/shinokada/svelte-lib-helpers#readme)
## Props
@prop children: Snippet
@prop footerType: 'sitemap' | 'default' | 'logo' | 'socialmedia' | undefined = 'default'
@prop class: string | undefined = ''
@prop ...attributes
-->
If the command doesn’t generate the expected output:
The subcommand docs5FromType
extracts prop types and default values from your Svelte components to generate documentation. It supports two common patterns for defining prop types:
Your component must use one of these patterns for prop definitions:
If the command doesn’t generate the expected output:
From the following props structure:
interface Props {
children: any;
drawerStatus: boolean;
toggleDrawer?: () => void;
position?: 'fixed' | 'absolute';
leftOffset?: string | undefined;
width?: string;
placement?: 'left' | 'right' | 'top' | 'bottom';
transitionParams: drawerTransitionParamTypes;
}
let {
children,
drawerStatus,
toggleDrawer,
position = 'fixed',
leftOffset = 'inset-y-0 start-0',
width = 'w-80',
placement = 'left',
transitionParams,
...attributes
}: Props = $props();
To:
<!--
@component
[Go to docs](https://github.com/shinokada/svelte-lib-helpers)
## Props
@props: children: any;
@props:drawerStatus: boolean;
@props:toggleDrawer?: () => void;
@props:position?: 'fixed' | 'absolute'; = 'fixed';
@props:leftOffset?: string | undefined; = 'inset-y-0 start-0';
@props:width?: string; = 'w-80';
@props:placement?: 'left' | 'right' | 'top' | 'bottom'; = 'left';
@props:transitionParams: drawerTransitionParamTypes;
-->
Or from the following structure:
// defined type in index.ts
import { type DropzoneProps as Props, dropzone } from '.';
let { children, value = $bindable<string | undefined>(), files = $bindable<FileList | null>(), class: className, ...restProps }: Props = $props();
To:
<!--
@component
[Go to docs](https://github.com/shinokada/svelte-lib-helpers#readme)
## Props
@prop children
@prop value = $bindable<string | undefined>()
@prop files = $bindable<FileList | null>()
@prop class: className
@prop ...restProps
-->
Add the following to your package.json scripts section:
"gen:docs5FromType": "node ./index.js docs5FromType",
The following commands will generate JSON files containing props, slots, and events information from all Svelte files in the src/lib directory, placing them in the routes/component-data directory.
The compo-data
subcommand works for Svelte 4 structure. This will generate a JSON file for each component with the following format from:
export let color: 'primary' | 'blue' | 'gray' | 'green' | 'red' | 'yellow' | 'pink' | 'purple' | 'white' | 'custom' | undefined = 'primary';
export let bg: string = 'text-gray-300';
// more lines for events and slots
to:
{"name":"Spinner","slots":[],"events":[],"props":[["color","'primary' | 'blue' | 'gray' | 'green' | 'red' | 'yellow' | 'pink' | 'purple' | 'white' | 'custom' | undefined","'primary'"],["bg","string","'text-gray-300'"]]}
The component-data
subcommand works for Svelte 4 structure. This will generate a JSON file for each component with the following format from:
interface $$Props extends ComponentProps<TransitionFrame> {
dismissable?: boolean;
defaultClass?: string;
}
export let dismissable: $$Props['dismissable'] = false;
export let defaultClass: $$Props['defaultClass'] = 'p-4 gap-3 text-sm';
// more lines for events and slots
to:
{"name":"Alert","slots":["icon","close-button"],"events":["on:close","on:click","on:change","on:keydown","on:keyup","on:focus","on:blur","on:mouseenter","on:mouseleave"],"props":[["dismissable","$$Props['dismissable']","false"],["defaultClass","$$Props['defaultClass']","'p-4 gap-3 text-sm'"]]}
The component5-data
subcommand works for Svelte 5 structure. This will generate a JSON file for each component with the following format from:
// defined type in index.ts
import { type CheckboxProps as Props, checkbox } from '.';
let { children, aria_describedby, color = 'primary', custom, inline, tinted = false, rounded = false, group = $bindable([]), choices = [], checked = $bindable(false), classLabel, indeterminate, class: className, ...restProps }: Props = $props();
to:
{
"name": "Checkbox",
"slots": [],
"events": [],
"props": [
[
"children",
"Snippet",
""
],
[
"aria_describedby",
"string",
""
],
[
"color",
"ColorType",
"'primary'"
],
[
"custom",
"boolean",
""
],
[
"inline",
"boolean",
""
],
[
"tinted",
"boolean",
"false"
],
[
"rounded",
"boolean",
"false"
],
[
"group",
"array",
"$bindable([])"
],
[
"choices",
"array",
"[]"
],
[
"checked",
"boolean",
"$bindable(false)"
],
[
"classLabel",
"string",
""
],
[
"indeterminate",
"boolean",
""
],
[
"className",
"",
""
]
]
}
The runes-data
subcommand works for Svelte 5 structure. This will generate a JSON file for each component with the following format from:
let {
children: Snippet,
footerType: 'sitemap' | 'default' | 'logo' | 'socialmedia' | undefined = 'default',
class: string | undefined = '',
...attributes
}: Props = $props();
to:
{"name":"Footer","props":[["children:Snippet",""],["footerType:'sitemap' | 'default' | 'logo' | 'socialmedia' | undefined",""],["class:string | undefined",""],["...attributes",""]]}
Below is an example of how you can integrate Svelte Lib Helpers subcommands into the scripts section of your package.json file within a SvelteKit project:
"scripts": {
// ...
"gen:exports": "node ./index.js exports",
"gen:docs": "node ./index.js docs",
"gen:docsFromProps": "node ./index.js docsFromProps",
"gen:docs5": "node ./index.js docs5",
"gen:docs5FromType": "node ./index.js docs5FromType",
"gen:compo-data": "node ./index.js compo-data",
"gen:componentData": "node ./index.js component-data",
"gen:componentDataRunes": "node ./index.js component-data-runes",
"gen:runes-data": "node ./index.js runes-data",
"copy:package": "node ./index.js package",
"lib-helpers": "npm run format && npm run gen:docs && npm run gen:compo-data && npm run package && npm run gen:exports && npm run copy:package",
"package:publish": "standard-version && git push --follow-tags origin main && npm publish"
}
Feel free to adjust these scripts according to your project’s needs, incorporating Svelte Lib Helpers to enhance your library development experience.
This project is licensed under the MIT License. For details, please refer to the LICENSE file.