svelte-5-documentor

Module for extracting metadata from Svelte 5 components

It analyzes Svelte 5 component ASTs to extract metadata (props, exports, generics, comments), inspired by Sveld but adapted for Svelte 5 and SvelteKit. TypeScript inference is not supported; only AST analysis is performed.

Usage

Module principal : src/lib/documentor.ts

Exclure des fichiers avec excludePattern

You can exclude files from the analysis with the excludePattern option (array of glob patterns, applied to all files) :

import { Svelte5Documentor } from './src/lib/documentor.ts';

const documentor = new Svelte5Documentor({
    recursive: true,
    filterExts: ['.svelte', '.svx'],
    excludePattern: ['**/node_modules/**', '**/*.test.svelte']
});

Exemple : parser un fichier Svelte en Node.js

import {parse_docinfo} from './src/lib/metadata.ts';
import {readFile} from 'fs/promises';

async function main() {
    const contents = await readFile('src/routes/Positioned.svelte', 'utf8');
    const {metadata, ast} = parse_docinfo(contents);
    console.log(metadata);
}

main();

This extract is a metadata object, which contains the metadata of the component.

To get the metadata from a component:

import {parse_docinfo} from '$lib/metadata.js;';

const metadata = parse_docinfo(`
<script lang="ts" generics="T, U extends string">
    const {
        some_simple_prop,
        some_bindable_prop = $bindable('fallback'),
    }: {
        /**
         * comments
         * go here
         *
         * etc
         */
        some_simple_prop: T;
        some_bindable_prop?: U;
    } = $props();

    export const export_with_type: Date = new Date();

  export const exported_needs_inference = 'TODO infer type for exports';
</script>
`);
/*
{
    "props": [
        {
            "name": "some_simple_prop",
            "comment": ["comments go here", "etc"],
            "type": "T",
            "optional": false,
            "bindable": false,
            "default": null
        },
        {
            "name": "some_bindable_prop",
            "comment": null,
            "type": "U",
            "optional": true,
            "bindable": true,
            "default": "'fallback'"
        }
    ],
    "exports": [
        {"name": "export_with_type", "comment": null, "type": "Date"},
        {"name": "exported_needs_inference", "comment": null, "type": null}
    ],
    "generics": "T, U extends string"
}
*/

import some_component_contents from '$routes/+layout.svelte?raw';
const metadata = parse_docinfo(some_component_contents);

import {ast_to_docinfo} from '$lib/metadata.js;';
const metadata = ast_to_docinfo(some_modern_svelte_ast, some_component_contents);

Also supports named props interfaces when defined in the same file, const {}: Props = $props();.

Tests at src/tests/metadata.test.ts and src/tests/samples.

// $lib/metadata.ts

export const parse_docinfo = (
    contents: string,
    parse_options?: Parameters<typeof parse>[1], // forces `modern: true`
) => Parsed_Docinfo;

export const ast_to_docinfo: (ast: AST.Root, contents: string) => Docinfo;

export interface Parsed_Docinfo {
    metadata: Docinfo;
    ast: AST.Root;
}

export interface Docinfo {
    props: Docinfo_Prop[];
    exports: Docinfo_Export[];
    generics: string | null; // TODO inference?
}

export interface Docinfo_Prop {
    name: string;
    comment: string[] | null;
    type: string; // TODO might be enhanced by inference
    optional: boolean;
    bindable: boolean;
    default: null | string;
}

export interface Docinfo_Export {
    name: string;
    comment: string[] | null;
    type: string | null; // TODO needs inference
}

Developer Workflows

• Install dependencies:

  npm i
  

• Run tests:

  npm test
  

• See parsed output in terminal:

  npx gro run src/tests/print_parsed.ts
  

This project was previously named svelte_docinfo_sketch and is now maintained as svelte-5-documentor.

License

Unlicense ⚘ public domain