Svelte-docster NPM

Generate metadata about your Svelte files from jsdoc.

🏠 Homepage

Install

This project was created to have something in between sveltedoc-parser and sveld. This project can be used to give simple data on what your svelte file exports.

npm i -D svelte-docster

Usage

const docster = require('svelte-docster');
//or
import docster from 'svelte-docster';

docster({
  // provide either the full path to the svelte file
  file: 'full/path/to/file.svelte',

  // or provide string content and the filename,
  content: '<script> ... </script> Svelte file',
  filename: 'App.svelte',
});

Output

{
  props: {
    propName: {
      value: string,
      valueType: 'Literal' | 'Identifier' | 'FunctionDeclaration' | null,
      localName: string,
      kind: 'let' | 'const' | 'function',
      required: boolean,
      description: string,
      tags: [
        {
          tag: string,
          type: string,
          name: string,
          description: string,
        },
        ...
      ]
    },
    ...
  }

  slots: {
    slotName: {
      type: string,
      description: string,
      content: string,
      attributes: {
        attributeName: {
          value: string,
          valueType: string,
        },
        ...
      }
    },
    ...
  },

  events: {
    eventName: {
      eventDetail: string,
      description: string,
      by?: "Element" | "InlineComponent",
      trigger?: string,
    },
    ...
  }

  typedef: {
    typeName: {
      value: string,
      description: string
    },
    ...
  }

  restProps: string,

  styles: {
    styleName: {
      description: string,
      default: string,
      type: string
    },
    ...
  },

  all: [array of all the JSDoc comments in the svelte file.],

  // from context='module'
  module: {
    exportedVariable: {
      value: string,
      valueType: 'Literal' | 'Identifier' | 'FunctionDeclaration' | null,
      localName: string,
      kind: 'let' | 'const' | 'function',
      required: boolean,
      description: string,
      tags: [
        {
          tag: string,
          type: string,
          name: string,
          description: string,
        },
        ...
      ]
    },
    ...
  }
}

{
  "propName": {
    "propName": {
      "value": "'value'",
      "valueType": "Literal",
      "localName": "propName",
      "kind": "let",
      "required": false,
      "description": "This is the prop description.",
      "tags": [
        {
          "tag": "type",
          "type": "string",
          "name": "",
          "description": ""
        }
      ]
    }
  }
}

Events

/**
 * @event {{cool: boolean}} button A very cool event.
 */

<button on:click></button>

Output

{
  "button": {
    "eventDetail": "{cool: boolean}",
    "description": "A very cool event."
  },
  "click": {
    "eventDetail": "window",
    "description": null,
    "by": "Element",
    "trigger": "button"
  }
}

Slots

/**
 * @slot {{prop1:string;}} default
 * @slot {{i:number;}} repeated
 */

<slot basic="prop" />
{#each Array(10) as _, i}
  <slot name="repeated" {i} />
{/each}

Output

{
  "default": {
    "type": "{prop1:string;}",
    "description": "",
    "attributes": {
      "basic": {
        "value": "prop",
        "valueType": "Text"
      }
    },
    "content": "<slot basic=\"prop\" />"
  },
  "repeated": {
    "type": "{i:number;}",
    "description": "",
    "attributes": {
      "name": {
        "value": "repeated",
        "valueType": "Text"
      },
      "i": {
        "value": "i",
        "valueType": "AttributeShorthand"
      }
    },
    "content": "<slot name=\"repeated\" {i} />"
  }
}

Styles

/**
 * @style {20px} --some-var Description of CSS variable
 * @style --another-var No default
 */

Output

{
  "--some-var": {
    "description": "Description of CSS variable",
    "default": "20px"
  },
  "--another-var": {
    "description": "No default",
    "default": ""
  }
}

restProps

/**
 * @restProps {button | h1}
 */

Output

{
  "restProps": "button | h1"
}

Typedef

/**
 * @typedef {string | boolean} RandomType cats > dogs
 * @typedef {{key1: {key2?: boolean}}} Nested some description
 */

Output

{
  "RandomType": {
    "value": "string | boolean",
    "description": "cats > dogs"
  },
  "Nested": {
    "value": "{key1: {key2?: boolean}}",
    "description": "some description"
  }
}