remark-svelte-auto-importDaniel Kasmeroglu - Nov 26, 2023 12:50

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 support but requires to add the corresponding import into 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 comests 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:

    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               : Debug,
    
    /* 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};

} /* ENDINTERFACE */

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

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.ComponentMap: prints out the component map configuration identified through the transformation process
  • Debug.RootBefore: prints the ast before the transformation
  • Debug.RootAfter: prints the ast after the transformation
  • Debug.All: enables all outputs (convenience value)
• debugComponentMap : boolean - Print out information of the identified components. Be aware that depending on your project this might be a big map which will be printed as a JSON string.
• debugRootBefore : boolean - Prints the root node before the transformation takes place.
• debugRootAfter : boolean - Prints the root node after the transformation successfully took place.
• 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.

Examples

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][flowbite-alert] this will cause an import such as this:

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

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 need 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.svelte';
</script>