reactive-meta-gen

Generate TypeScript meta info with 'reactive-vscode' and Markdown tables for VS Code extension from package.json

This was inspired by vscode-ext-gen. I planed to submit a PR for this change, but after thought carefull, duo to the huge changes, I created a new cli tool for these features. Any way this idea is base on antfu/vscoe-ext-gen.

Usage

1npx reactive-meta-gen

Under the VS Code extension project root

Continuous Update

1. Add following to package.json

1  "scripts": {
2
3    "prepare": "pnpm run update",
4    "update": "vscode-ext-gen ./package.json --readme ./README.md --output ./src/generated-meta.ts"
5  },
6

2. We recommend using the Run on Save extension with the following config in your .vscode/settings.json or .code-workspace to always generate the meta file on save:

1{
2  "emeraldwalk.runonsave": {
3    "commands": [
4      {
5        "match": "package.json",
6        "isAsync": true,
7        "cmd": "npm run update"
8      }
9    ]
10  }
11}

Examples

Generates src/generated-meta.ts file with the following content which syncs with your package.json:

1// This file is generated by `reactive-meta-gen`. Do not modify manually.
2// @see https://github.com/calmripple/reactive-meta-gen
3
4// Meta info
5
6import { defineConfigObject, defineConfigs } from 'reactive-vscode'
7
8export const publisher = "calmripple"
9export const name = "sample"
10export const version = "0.8.1"
11export const displayName = "sample IntelliSense"
12export const description = "Intelligent sample previewing and searching for VS Code"
13export const extensionId = `${publisher}.${name}`
14
15/**
16 * Type union of all commands
17 */
18export type CommandKey = 
19  | "sample.toggle-annotations"
20  | "sample.toggle-inplace"
21  | "sample.clear-cache"
22
23/**
24 * Commands map registed by `calmripple.sample`
25 */
26export const commands = {
27  /**
28   * Toggle Annotations
29   * @value `sample.toggle-annotations`
30   * @example
31   * useCommand(commands.toggleAnnotations, async () => {
32   *   //do actions or update config 
33   * })
34   */
35  toggleAnnotations: "sample.toggle-annotations",
36  /**
37   * Toggle In-place Mode
38   * @value `sample.toggle-inplace`
39   * @example
40   * useCommand(commands.toggleInplace, async () => {
41   *   //do actions or update config 
42   * })
43   */
44  toggleInplace: "sample.toggle-inplace",
45  /**
46   * Clear icon cache
47   * @value `sample.clear-cache`
48   * @example
49   * useCommand(commands.clearCache, async () => {
50   *   //do actions or update config 
51   * })
52   */
53  clearCache: "sample.clear-cache",
54} satisfies Record<string, CommandKey>
55
56/**
57 * Type union of all configs
58 */
59
60/**
61 * Config keys of `sample`
62 */
63export interface Sample {
64  /**
65   * Use icon graph to replace the icon name.
66   * @key `sample.inplace`
67   * @default `true`
68   * @type `boolean`
69   */
70  "inplace": boolean,
71  /**
72   * Enabled sample inline annotations
73   * @key `sample.annotations`
74   * @default `true`
75   * @type `boolean`
76   */
77  "annotations": boolean,
78  /**
79   * Position the icon before or after the icon name
80   * @key `sample.position`
81   * @default `"before"`
82   * @type `string`
83   */
84  "position": ("before" | "after"),
85  /**
86   * Icon color hex for inline displaying
87   * @key `sample.color`
88   * @default `"auto"`
89   * @type `string`
90   */
91  "color": string,
92  /**
93   * Delimiters for separating between collection id and icon id
94   * @key `sample.delimiters`
95   * @default `[":","--","-","/"]`
96   * @type `array`
97   */
98  "delimiters": string[],
99  /**
100   * Prefixes for matching
101   * @key `sample.prefixes`
102   * @default `["","i-","~icons/"]`
103   * @type `array`
104   */
105  "prefixes": string[],
106  /**
107   * Suffixes for matching
108   * @key `sample.suffixes`
109   * @default `["","i-"]`
110   * @type `array`
111   */
112  "suffixes": string[],
113  /**
114   * Array of language IDs to enable annotations
115   * @key `sample.languageIds`
116   * @default `["javascript","javascriptreact","typescript","typescriptreact","vue","svelte","html","pug","json","yaml"]`
117   * @type `array`
118   */
119  "languageIds": string[],
120  /**
121   * Collection IDs to be included for detection
122   * @key `sample.includes`
123   * @default `null`
124   * @type `array`
125   */
126  "includes": (("academicons" | "akar-icons" | "ant-design" | "arcticons" | "basil" | "bi" | "bitcoin-icons" | "bpmn" | "brandico" | "bx" | "bxl" | "bxs" | "bytesize" | "carbon" | "cbi" | "charm" | "ci" | "cib" | "cif" | "cil" | "circle-flags" | "circum" | "clarity" | "codicon" | "covid" | "cryptocurrency" | "cryptocurrency-color" | "dashicons" | "devicon" | "devicon-plain" | "ei" | "el" | "emojione" | "emojione-monotone" | "emojione-v1" | "entypo" | "entypo-social" | "eos-icons" | "ep" | "et" | "eva" | "f7" | "fa" | "fa-brands" | "fa-regular" | "fa-solid" | "fa6-brands" | "fa6-regular" | "fa6-solid" | "fad" | "fe" | "feather" | "file-icons" | "flag" | "flagpack" | "flat-color-icons" | "flat-ui" | "flowbite" | "fluent" | "fluent-emoji" | "fluent-emoji-flat" | "fluent-emoji-high-contrast" | "fluent-mdl2" | "fontelico" | "fontisto" | "formkit" | "foundation" | "fxemoji" | "gala" | "game-icons" | "geo" | "gg" | "gis" | "gravity-ui" | "gridicons" | "grommet-icons" | "guidance" | "healthicons" | "heroicons" | "heroicons-outline" | "heroicons-solid" | "humbleicons" | "ic" | "icomoon-free" | "icon-park" | "icon-park-outline" | "icon-park-solid" | "icon-park-twotone" | "iconamoon" | "iconoir" | "icons8" | "il" | "ion" | "iwwa" | "jam" | "la" | "lets-icons" | "line-md" | "logos" | "ls" | "lucide" | "mage" | "majesticons" | "maki" | "map" | "marketeq" | "material-symbols" | "material-symbols-light" | "mdi" | "mdi-light" | "medical-icon" | "memory" | "meteocons" | "mi" | "mingcute" | "mono-icons" | "mynaui" | "nimbus" | "nonicons" | "noto" | "noto-v1" | "octicon" | "oi" | "ooui" | "openmoji" | "oui" | "pajamas" | "pepicons" | "pepicons-pencil" | "pepicons-pop" | "pepicons-print" | "ph" | "pixelarticons" | "prime" | "ps" | "quill" | "radix-icons" | "raphael" | "ri" | "si-glyph" | "simple-icons" | "simple-line-icons" | "skill-icons" | "solar" | "streamline" | "streamline-emojis" | "subway" | "svg-spinners" | "system-uicons" | "tabler" | "tdesign" | "teenyicons" | "token" | "token-branded" | "topcoat" | "twemoji" | "typcn" | "uil" | "uim" | "uis" | "uit" | "uiw" | "unjs" | "vaadin" | "vs" | "vscode-icons" | "websymbol" | "whh" | "wi" | "wpf" | "zmdi" | "zondicons")[] | null),
127  /**
128   * Collection IDs to be excluded for detection
129   * @key `sample.excludes`
130   * @default `null`
131   * @type `array`
132   */
133  "excludes": (("academicons" | "akar-icons" | "ant-design" | "arcticons" | "basil" | "bi" | "bitcoin-icons" | "bpmn" | "brandico" | "bx" | "bxl" | "bxs" | "bytesize" | "carbon" | "cbi" | "charm" | "ci" | "cib" | "cif" | "cil" | "circle-flags" | "circum" | "clarity" | "codicon" | "covid" | "cryptocurrency" | "cryptocurrency-color" | "dashicons" | "devicon" | "devicon-plain" | "ei" | "el" | "emojione" | "emojione-monotone" | "emojione-v1" | "entypo" | "entypo-social" | "eos-icons" | "ep" | "et" | "eva" | "f7" | "fa" | "fa-brands" | "fa-regular" | "fa-solid" | "fa6-brands" | "fa6-regular" | "fa6-solid" | "fad" | "fe" | "feather" | "file-icons" | "flag" | "flagpack" | "flat-color-icons" | "flat-ui" | "flowbite" | "fluent" | "fluent-emoji" | "fluent-emoji-flat" | "fluent-emoji-high-contrast" | "fluent-mdl2" | "fontelico" | "fontisto" | "formkit" | "foundation" | "fxemoji" | "gala" | "game-icons" | "geo" | "gg" | "gis" | "gravity-ui" | "gridicons" | "grommet-icons" | "guidance" | "healthicons" | "heroicons" | "heroicons-outline" | "heroicons-solid" | "humbleicons" | "ic" | "icomoon-free" | "icon-park" | "icon-park-outline" | "icon-park-solid" | "icon-park-twotone" | "iconamoon" | "iconoir" | "icons8" | "il" | "ion" | "iwwa" | "jam" | "la" | "lets-icons" | "line-md" | "logos" | "ls" | "lucide" | "mage" | "majesticons" | "maki" | "map" | "marketeq" | "material-symbols" | "material-symbols-light" | "mdi" | "mdi-light" | "medical-icon" | "memory" | "meteocons" | "mi" | "mingcute" | "mono-icons" | "mynaui" | "nimbus" | "nonicons" | "noto" | "noto-v1" | "octicon" | "oi" | "ooui" | "openmoji" | "oui" | "pajamas" | "pepicons" | "pepicons-pencil" | "pepicons-pop" | "pepicons-print" | "ph" | "pixelarticons" | "prime" | "ps" | "quill" | "radix-icons" | "raphael" | "ri" | "si-glyph" | "simple-icons" | "simple-line-icons" | "skill-icons" | "solar" | "streamline" | "streamline-emojis" | "subway" | "svg-spinners" | "system-uicons" | "tabler" | "tdesign" | "teenyicons" | "token" | "token-branded" | "topcoat" | "twemoji" | "typcn" | "uil" | "uim" | "uis" | "uit" | "uiw" | "unjs" | "vaadin" | "vs" | "vscode-icons" | "websymbol" | "whh" | "wi" | "wpf" | "zmdi" | "zondicons")[] | null),
134  /**
135   * CDN entry of sample icon-sets
136   * @key `sample.cdnEntry`
137   * @default `"https://icones.js.org/collections"`
138   * @type `string`
139   */
140  "cdnEntry": string,
141  /**
142   * JSON paths for custom collection
143   * @key `sample.customCollectionJsonPaths`
144   * @default `[]`
145   * @type `array`
146   */
147  "customCollectionJsonPaths": string[],
148  /**
149   * Collection IDs Map for collection name alias, e.g. { 'mc': 'mingcute' }
150   * @key `sample.customCollectionIdsMap`
151   * @default `{}`
152   * @type `object`
153   */
154  "customCollectionIdsMap": Record<string, unknown>,
155  /**
156   * JSON paths for custom aliases
157   * @key `sample.customAliasesJsonPaths`
158   * @default `[]`
159   * @type `array`
160   */
161  "customAliasesJsonPaths": string[],
162  /**
163   * Only use the icon aliases. Non aliased icons will be ignored.
164   * @key `sample.customAliasesOnly`
165   * @default `false`
166   * @type `boolean`
167   */
168  "customAliasesOnly": boolean,
169}
170
171/**
172 * Scoped defaults of `sample`
173 */
174const _sample = {
175/**
176 * scope: `sample`
177 */
178  scope: "sample",
179/**
180 * Keys' defaults of `sample`
181 */
182  defaults: {
183    "inplace": true,
184    "annotations": true,
185    "position": "before",
186    "color": "auto",
187    "delimiters": [":","--","-","/"],
188    "prefixes": ["","i-","~icons/"],
189    "suffixes": ["","i-"],
190    "languageIds": ["javascript","javascriptreact","typescript","typescriptreact","vue","svelte","html","pug","json","yaml"],
191    "includes": null,
192    "excludes": null,
193    "cdnEntry": "https://icones.js.org/collections",
194    "customCollectionJsonPaths": [],
195    "customCollectionIdsMap": {},
196    "customAliasesJsonPaths": [],
197    "customAliasesOnly": false,
198  } satisfies Sample,
199}
200
201/**
202 * Reactive ConfigObject of `sample`
203 * @example
204 * let configValue = sampleConfigObject.inplace //get value 
205 * sampleConfigObject.inplace = true // set value
206 * sampleConfigObject.$update("inplace", !configValue, ConfigurationTarget.Workspace, true)
207 */
208export const sampleConfigObject = defineConfigObject<Sample>(
209  _sample.scope,
210  _sample.defaults
211)
212/**
213 * Reactive ToConfigRefs of `sample`
214 * @example
215 * let configValue:boolean =sampleConfigs.inplace.value //get value 
216 * sampleConfigs.inplace.value = true // set value
217 * //update value to ConfigurationTarget.Workspace/ConfigurationTarget.Global/ConfigurationTarget.WorkspaceFolder
218 * sampleConfigs.inplace.update(true, ConfigurationTarget.WorkspaceFolder, true)
219 */
220export const sampleConfigs = defineConfigs<Sample>(
221  _sample.scope,
222  _sample.defaults
223)
224

On usage:

1import { commands, sampleConfigObject, sampleConfigs } from './output/sample'
2import { defineExtension, useCommands, watchEffect } from 'reactive-vscode'
3
4import { window } from 'vscode'
5
6const { activate, deactivate } = defineExtension(() => {
7    watchEffect(() => {
8        //watch value change
9        window.showInformationMessage(`sampleConfigs.annotations.value:${sampleConfigs.annotations.value}`)
10    })
11    useCommands({
12        [commands.toggleAnnotations]: async () => {
13            //update value to ConfigurationTarget.Workspace/ConfigurationTarget.Global/ConfigurationTarget.WorkspaceFolder
14            sampleConfigs.inplace.update(!sampleConfigs.inplace.value)
15        }
16    })
17})
18
19export { activate, deactivate }

For a full example, check this file

Generate Docs

Add comments <!-- commands --> and <!-- configs --> as the slots in your README.md:

1# Your Extension
2
3## Commands
4
5<!-- commands -->
6<!-- commands -->
7
8## Configurations
9
10<!-- configs -->
11<!-- configs -->

They will be replaced with the generated tables when you run npx reactive-meta-gen.

Sponsors

Waiting for your support!

License

MIT License © 2023-PRESENT Calm Ripple