vuegc
v2.1.0
Published
CLI to generate a Vue 3 single-file component (script setup, TypeScript) in your project src/ folder
Maintainers
Readme
vuegc
CLI to generate a Vue 3 single-file component (.vue) in your project's src/ folder: <script setup>, TypeScript, CSS pre-processors, props and events.
For Vue 2, use vuegc 1: npm install -g vuegc@1 (see Versions).
Install
npm install -g vuegcOr run it without installing: npx vuegc --name HelloWorld.
Usage
Run it at the root of a Vue 3 project (the folder that contains src/main.js or src/main.ts, creating the app with createApp, and src/App.vue), e.g. a Vite or Vue CLI 5 project:
vuegc --name HelloWorld.vue [--scoped [true|false]] [--style css] [--path components] [--blank] [--force] [--dry-run] [--no-template|--no-script|--no-style] [--props title,items] [--emits update,close] [--module] [--options] [--ts] [--template pug] [--test] [--story]| Flag | Description | Default |
|---|---|---|
| --name | Required. Name of the component, with or without .vue | |
| --style | CSS pre-processor: css, scss, sass (indented syntax), less or stylus | css |
| --scoped | scoped attribute on <style> (--scoped false to remove it) | true |
| --path | Folder inside src/ for the component, created if missing | src/ |
| --blank | Empty template and style, without the demo content | false |
| --force | Overwrite the component if it already exists | false |
| --dry-run | Print the component instead of writing it; same checks as a real run | false |
| --no-template, --no-script, --no-style | Leave the section out (at least one must remain). Without the template, the component needs a script with something in it: --props, --emits or --options | false |
| --props | Comma-separated prop names, e.g. title,items, declared as title: null (any type) | none |
| --emits | Comma-separated event names, e.g. update:modelValue,close: defineEmits([...]) / emits: [...] | none |
| --module | CSS modules: <style module> and :class="$style.root" instead of scoped | false |
| --options | Options API (export default { name, props, data, methods }) instead of <script setup> | false |
| --ts | TypeScript: lang="ts", typed defineProps<{ … }>() / defineEmits<{ … }>(), defineComponent() with --options | false |
| --template | Template language: html, or pug (<template lang="pug">, needs the pug package) | html |
| --test | Also write a Vitest test next to the component: Name.spec.js (.spec.ts with --ts) | false |
| --story | Also write a Storybook story next to the component: Name.stories.js (.stories.ts with --ts) | false |
| --help, -h | Show the help (also shown without any argument) | |
Examples:
vuegc --name HelloWorld # src/HelloWorld.vue
vuegc --name Button --path components/ui # src/components/ui/Button.vue
vuegc --name Card --props title,items --emits close # props and events
vuegc --name Card --ts --style scss --blank # TypeScript, scss, empty
vuegc --name Card --options # Options API
vuegc --name Card --template pug # Pug template
vuegc --name Card --path components --test # and src/components/Card.spec.js
vuegc --name Card --test --story # and src/Card.spec.js, src/Card.stories.jsAn existing component (or its test, or its story) is never overwritten without --force. On failure, vuegc prints the reason and exits with code 1.
Generated component
vuegc --name HelloWorld generates src/HelloWorld.vue:
<template>
<div id="HelloWorld"> Component <span>HelloWorld</span> generated by <a href="">VueGC</a> </div>
</template>
<script setup>
</script>
<style lang="css" scoped>
#HelloWorld {
font-size: 16px;
line-height: 150%;
}
span { font-weight: bold; }
a { font-style: italic; }
</style>vuegc --name Card --props title,items --emits update:modelValue --blank:
<template>
<div></div>
</template>
<script setup>
const props = defineProps({
title: null,
items: null
});
const emit = defineEmits(["update:modelValue"]);
</script>
<style lang="css" scoped>
</style>The same with --ts:
<template>
<div></div>
</template>
<script setup lang="ts">
const props = defineProps<{
title?: unknown;
items?: unknown;
}>();
const emit = defineEmits<{
"update:modelValue": [...args: unknown[]];
}>();
</script>
<style lang="css" scoped>
</style>Test
vuegc --name Card --props title --test also generates src/Card.spec.js, a Vitest test mounting the component with Vue Test Utils:
import { describe, it, expect } from "vitest";
import { mount } from "@vue/test-utils";
import Card from "./Card.vue";
describe("Card", () => {
it("renders", () => {
const wrapper = mount(Card, { props: { title: "title" } });
expect(wrapper.exists()).toBe(true);
expect(wrapper.text()).toContain("Card");
});
});It runs as is in a project made by npm create vue@latest with Vitest, which sets everything up. In another project, install vitest, @vue/test-utils and jsdom, and set environment: "jsdom" in the Vitest config; vuegc reminds you when vitest or @vue/test-utils is missing from package.json.
Story
vuegc --name Card --props title --emits close --story also generates src/Card.stories.js, a Storybook story in Component Story Format 3, with the props as args and a spy for each event:
import { fn } from "storybook/test";
import Card from "./Card.vue";
export default {
component: Card
};
export const Default = {
args: {
title: "title",
onClose: fn()
}
};With --ts, Card.stories.ts is typed with Meta and StoryObj from @storybook/vue3-vite, like the stories Storybook generates. There is no title: Storybook names the story after the file's path (src/components/Card.stories.js → components/Card). Set up Storybook with npm create storybook@latest; vuegc reminds you when storybook is missing from package.json.
Use as a library
const { vuegc } = require("vuegc");
// Generates <cwd>/src/components/HelloWorld.vue and returns its path
vuegc({ name: "HelloWorld", style: "css", scoped: true, path: "components", blank: false, force: false, cwd: process.cwd() });Every CLI flag has an option: style, scoped, template, path, blank, force, dryRun, noTemplate, noScript, noStyle, props and emits (arrays), cssModule (--module), optionsApi (--options), ts, test, story, plus cwd.
On failure, vuegc() throws instead of exiting; errorHandler(err) prints the same message as the CLI and exits.
TypeScript: types are included (vuegc.d.ts), nothing to install:
import { vuegc, type VuegcOptions } from "vuegc";
const options: VuegcOptions = { name: "Card", style: "less", props: ["title"] };
const file: string = vuegc(options);Versions
| vuegc | Vue | Install |
|---|---|---|
| 1.x | Vue 2 | npm install -g vuegc@1 |
| 2.x | Vue 3 | npm install -g vuegc |
vuegc 2 refuses a Vue 2 project (new Vue) and points to vuegc 1.
See the CHANGELOG for the details of each version.
Migrating from 1.x
| 1.x | 2.x | To get the 1.x output |
|---|---|---|
| Vue 2 projects | Vue 3 projects only | stay on vuegc@1 for Vue 2 |
| scss by default | css by default | --style scss |
| Options API (export default { … }) | <script setup> | --options |
So in a Vue 3 project, vuegc --name Card --options --style scss generates what vuegc 1 generated.
Development
npm install
npm test # run the tests once
npm run test:watch # re-run on every changeTests use Vitest (Node 22.12+ or 24 for development):
- CLI tests create a temporary Vue project, run
vuegcin it, and check the output, the exit code and the generated file. - Library tests call
vuegc()anderrorHandler()directly, with mocks forconsole.logandprocess.exit. - Snapshot tests lock the generated output (
npx vitest run -uto update them on purpose). - Type tests (
test/*.test-d.ts) checkvuegc.d.tswith TypeScript, so the types can't drift from the code.
