@kasisoft/remark-svelte-auto-import NPM

remark-svelte-auto-import

What is this?

This plugin is part of the remark plugin infrastructure and meant to be used in conjunction with mdsvex. mdsvex allows to use Markdown to write your pages within the Svelte framework. Obviously it's nice to use components within these Markdown files which is supported but requires to add the corresponding import within the Markdown file. For instance:

<script>
    import { Chart } from '@chartfactory';
</script>
# Title

Here is my Chart:

<Chart />

Though feasible the script tag is somewhat annoying here as it's only reason for existence is to satisfy technical requirements. This is where this plugin remark-svelte-auto-import comes into action. It integrates with the remark infrastructure and generates these imports. Using it would change the above section to this one:

# Title

Here is my Chart:

<Chart />

When should I use this?

This plugin is meant to be used in conjunction with mdsvex and only needed if you intend to use Svelte components within your Markdown.

Install

This package is ESM only. In Node.js (version 18+), install with pnpm:

pnpm install @kasisoft/remark-svelte-auto-import

Usage

Setup your Svelte project and install mdsvex (see mdsvexdocs)

Your project will now contain a file named mdsvex.config.js.

Import the plugin:

import { remarkSvelteAutoImport } from '@kasisoft/remark-svelte-auto-import';

Update the array of remark plugins without a configuration:

const config = defineConfig({
    ...
    remarkPlugins: [remarkSvelteAutoImport],
    ...
});

with a configuration (note: each entry is a list here):

const myconfig = {...DEFAULT_OPTIONS, debugComponentMap: true};
const config = defineConfig({
    ...
    remarkPlugins: [
        [remarkSvelteAutoImport, myconfig]
    ],
    ...
});

Configuration

The configuration is fully typed using Typescript. RemarkSvelteAutoImportOptions is defined as followed:

export interface RemarkSvelteAutoImportOptions {

    /* Debug.{None, Default, RootBefore, RootAfter, ScriptBefore, ScriptAfter, ComponentMap, All}
     * It's okay to use a list of string values for the debugging levels.
     * For instance: ['RootBefore', 'RootAfter']
     */
    debug              : Debug | string | string[];

    /* generate ts lang attribute for non existent script nodes */
    scriptTS?           : boolean;

    /* scan for components */
    directories?       : string[];
    patterns?          : string[];

    /* alternatively/additionally provide a mapping between components and modules  */
    componentMap?      : {[component: string]: string};

    /* mapping for local components (unless mapped in componentMap) */
    localComponents?   : {[pathPrefix: string]: string};

} /* ENDINTERFACE */

You can import the default settings DEFAULT_OPTIONS with the following setup:

import { DEFAULT_OPTIONS } from '@kasisoft/remark-svelte-auto-import';

# which would include this block:
export const DEFAULT_OPTIONS: RemarkSvelteAutoImportOptions = {
    debug               : Debug.None,
    scriptTS            : true,
    directories         : [
        'node_modules/'
    ],
    patterns            : [
        '**/*.svelte'
    ]
};

debug : Debug - Combine flags of Debug in order to generate debug statements:
- Debug.None: no output (just a convenience value)
- Debug.Default: some basic output
- Debug.RootBefore: prints the ast before the transformation
- Debug.RootAfter: prints the ast after the transformation
- Debug.ScriptBefore: prints the script node before the transformation
- Debug.ScriptAfter: prints the script node after the transformation
- Debug.ComponentMap: prints out the component map configuration identified through the transformation process
- Debug.All: enables all outputs (convenience value)
- Using an array of strings representing these debug settings is also possible. For instance:
  - 'ScriptBefore', 'RootAfter'
scriptTS : boolean - By default a lang="ts" will be added to each create script tag. If set to false this won't happen.
directories : string[] - A list of directories to parse for svelte components.
patterns : string[] - A list of patterns to identify svelte components.
componentMap : {component: string: string} - A map that allows to specify the components and their respective modules. If you configure this by yourself you can use empty directories and patterns. If you additionally scan for components this componentMap will override the scanned settings.
localComponents : {pathPrefix: string: string} - A map of path prefixes used to map the location of the components.

Examples

I'm using this plugin in the following example project: remark-image-tools so you get a working example out of the box (look for the component Example).

Here are some basic scenarios as well:

Only imported components

If all components you are using are provided though npm dependencies you can just add the node_modules directory to the configuration:

const config = {
    ...
    directories         : [
        'node_modules/'
    ],
    patterns            : [
        '**/*.svelte'
    ]
    ...
}

Let's say you have the component Alert from the flowbite svelte this will cause an import such as this:

<script>
    import { Alert } from 'flowbite-svelte';
</script>

With custom written components

However if you intend to use your own components you need to provide a corresponding mapping to refer to such a component. Let's say you have a component Garlic within src/lib/components/Garlic.svelte you to provide a corresponding path mapping such as this:

const config = {
    ...
    localComponents: {
        'src/lib': '$lib'
    }
    ...
}

This causes the location src/lib/components/Garlic.svelte to be mapped to $lib/components/Garlic resulting in this script:

<script>
    import { Garlic } from '$lib/components/Garlic';
</script>

Contributing

If you want to contribute I'm happy for any kind of feedback or bug reports. Please create issues and pull requests as you like but be aware that it may take some time for me to react.