Skip to content

Commit 3fcd980

Browse files
skirtles-codeskirtles-code
committed
More documentation
1 parent 1b6c3b5 commit 3fcd980

File tree

3 files changed

+209
-0
lines changed

3 files changed

+209
-0
lines changed

‎docs/.vitepress/config.mts

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,9 @@ export default defineConfigWithTheme({
4646
{
4747
text: 'Introduction',
4848
link: '/introduction'
49+
}, {
50+
text: 'The questions explained',
51+
link: '/questions'
4952
}
5053
]
5154
}

‎docs/src/introduction.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,3 +47,10 @@ Optional features include:
4747
- ESLint and ESLint Stylistic
4848

4949
The new project doesn't have any dependencies on special packages. It mostly uses the same dependencies as the official `create-vue` scaffolding tool, plus some widely used packages such as VitePress and ESLint Stylistic. In particular, there aren't any dependencies that tie you to the scaffolding tool.
50+
51+
Currently unsupported (you'd need to configure them yourself):
52+
53+
- JSX/TSX
54+
- Prettier
55+
- Other Vue libraries, such as Vue Router or Pinia
56+
- E2E testing

‎docs/src/questions.md

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
<style scoped>
2+
.mock-terminal {
3+
background: #ccc;
4+
border: 3px solid #ccc;
5+
border-radius: 5px;
6+
box-shadow: 5px 5px 5px rgba(0, 0, 0, 0.5);
7+
margin: 16px 0;
8+
overflow: hidden;
9+
}
10+
11+
.mock-terminal > .mock-terminal-heading {
12+
color: #000;
13+
padding: 5px 10px;
14+
}
15+
16+
.mock-terminal > pre {
17+
background: #111;
18+
box-shadow: 0 0 3px 2px #000 inset;
19+
color: #fff;
20+
margin: 0;
21+
overflow: auto;
22+
padding: 10px;
23+
}
24+
25+
.mock-terminal > pre > .check {
26+
color: #26a269;
27+
}
28+
29+
.mock-terminal > pre > a:not(:hover) {
30+
color: inherit;
31+
text-decoration: none;
32+
}
33+
</style>
34+
35+
# Questions
36+
37+
<div class="mock-terminal">
38+
<div class="mock-terminal-heading">Terminal</div>
39+
<pre>$ pnpm create @skirtle/vue-lib --extended
40+
&nbsp;
41+
<span class="check">✔</span> <a href="#package-name">Package name … @skirtle/test-project</a>
42+
<span class="check">✔</span> <a href="#target-directory">Target directory … test-project</a>
43+
<span class="check">✔</span> <a href="#main-package-directory">Main package directory … test-project</a>
44+
<span class="check">✔</span> <a href="#global-variable-name">Global variable name … TestProject</a>
45+
<span class="check">✔</span> <a href="#github-path">GitHub path (optional) … skirtles-code/test-project</a>
46+
<span class="check">✔</span> <a href="#include-eslint">Include ESLint? … No / Yes</a>
47+
<span class="check">✔</span> <a href="#include-eslint-stylistic">Include ESLint Stylistic for formatting? … No / Yes</a>
48+
<span class="check">✔</span> <a href="#include-vitepress">Include VitePress for documentation? … No / Yes</a>
49+
<span class="check">✔</span> <a href="#include-github-pages">Include GitHub Pages config for documentation? … No / Yes</a>
50+
<span class="check">✔</span> <a href="#include-playground">Include playground application for development? … No / Yes</a>
51+
<span class="check">✔</span> <a href="#include-examples">Include example code? … No, just configs / Yes</a>
52+
<span class="check">✔</span> <a href="#configure-src-alias">Configure @ as an alias for src? … No / Yes</a>
53+
<span class="check">✔</span> <a href="#configure-test-variable">Configure global __TEST__ variable?</a></pre>
54+
</div>
55+
56+
## Package name
57+
58+
This name will be used to populate the `name` field for your package's `package.json`. This field is the unique identifier for all packages published to the npm registry.
59+
60+
The newly created project will also use this name in various other places, such as in the generated docs and in example code.
61+
62+
Using a scoped package name is recommended, but not mandatory. Scopes provide a namespace, ensuring that package names don't clash within the npm registry. For example, several official Vue packages are scoped to `@vue`, e.g. `@vue/reactivity` and `@vue/test-utils`. This CLI tool used the scoped name `@skirtle/create-vue-lib`.
63+
64+
You need to register an account with npm before you can publish packages to the registry. While you don't need to create an account immediately, you may want to give some thought to what names are available before you start. Packages can be scoped using either a user name or an organization name registered with npm.
65+
66+
To learn more about scopes see <https://docs.npmjs.com/about-scopes>.
67+
68+
## Target directory
69+
70+
The name of the directory (folder) where the project will be created. This directory will be created in the current working directory.
71+
72+
If the directory already exists the files will be overwritten. This can be useful when performing upgrades, though you should ensure all old files are stored in source control first, so you can review the diffs and decide which changes to keep.
73+
74+
The special value `.` can also be used to indicate that files should be placed in the current directory.
75+
76+
The directory can be renamed after the project is created. None of the files within the project depend on the name of this folder.
77+
78+
The tool should only create files within the specified directory. It won't edit any global configuration or files elsewhere on the filesystem. If you want to delete the project you can just delete this directory.
79+
80+
## Main package directory
81+
82+
:::info NOTE
83+
This question is only asked when using the `--extended` flag.
84+
:::
85+
86+
The new project will have a directory structure something like this:
87+
88+
```
89+
📁 packages
90+
📁 docs
91+
📁 playground
92+
📁 <main-package-directory>
93+
```
94+
95+
The main package directory sits alongside the `docs` and `playground` packages and is used to hold the source code for the library itself.
96+
97+
A directory structure similar to this is used by various libraries in the Vue ecosystem. For example, see Pinia at <https://github.com/vuejs/pinia/tree/v3/packages>.
98+
99+
By default, this will be the same as the package name, but with any scope removed. So, for example, if you called the package `@skirtle/test-project` then the main package directory will be called `test-project`.
100+
101+
## Global variable name
102+
103+
:::info NOTE
104+
This question is only asked when using the `--extended` flag.
105+
:::
106+
107+
Libraries need to be built in a variety of formats, so they can be consumed in different use cases. A *global* build is used by projects that aren't using build tools, such as those that pull in libraries from a CDN.
108+
109+
Global builds don't support `import` or `require()`, but instead expose the library via a global variable in the browser. For example, Vue uses the global variable `Vue` in its global builds.
110+
111+
The global variable name should closely match the name of your library. For example, if your library is called `@skirtle/test-project` then the default global variable name would be `TestProject`.
112+
113+
## GitHub path
114+
115+
If you intend to store your project on GitHub then you should specify the path here. The remote repo doesn't need to exist yet, it is just used to populate fields in files such as `package.json` and the docs.
116+
117+
The GitHub path should be in the form `username/repo-name`.
118+
119+
For example, this project has its repository at `https://github.com/skirtles-code/create-vue-lib`, so the GitHub path is `skirtles-code/create-vue-lib`.
120+
121+
While answering this question is optional, it can be especially useful if you intend to use GitHub Pages to host your documentation, as the generated configuration files will be much closer to their final form.
122+
123+
## Include ESLint?
124+
125+
Include configuration for ESLint. This will be very similar to the default configuration generated by the official [`create-vue`](https://github.com/vuejs/create-vue) tool.
126+
127+
`simple-git-hooks` and `lint-staged` will also be configured in the root `package.json` to automatically check files when they're committed to Git.
128+
129+
## Include ESLint Stylistic for formatting?{#include-eslint-stylistic}
130+
131+
[ESLint Stylistic](https://eslint.style/) is a code formatter based on ESLint.
132+
133+
Currently, this is the only formatter that is supported by this CLI tool, but you can configure others yourself after the project is created.
134+
135+
## Include VitePress for documentation?{#include-vitepress}
136+
137+
[VitePress](https://vitepress.dev/) has become the standard tool for library documentation in the Vue community. If you intend to publish your package publicly then you probably want to use VitePress for your documentation.
138+
139+
Very small libraries might prefer to just use a GitHub `README.md` instead. Large libraries might prefer to house the documentation in a separate repo. But most libraries are somewhere in the middle, and this option works well for them. For example, you can see this approach being used by both [Vue Router](https://github.com/vuejs/router/tree/main/packages) and [Pinia](https://github.com/vuejs/pinia/tree/v3/packages).
140+
141+
VitePress will be configured with an `alias` to allow you to access your library within the documentation. This will use the library source code directly, without needing a build or release of the library.
142+
143+
## Include GitHub Pages config for documentation?{#include-github-pages}
144+
145+
You'll only see this question if you chose to include VitePress in the previous question.
146+
147+
Selecting this option will generate configuration files for deploying your documentation to GitHub Pages via a GitHub Action.
148+
149+
When you're ready to deploy the documentation, you'll need to enable deployment in the settings for your GitHub repository:
150+
151+
1. Go to **Settings** / **Pages**.
152+
2. Select a **Source** value of **GitHub Actions**.
153+
3. You may be prompted to create a configuration file. That isn't necessary if you're using the configuration generated by this tool.
154+
155+
## Include playground application for development?{#include-playground}
156+
157+
While you're developing your library, you can use the playground application to experiment and try out your changes.
158+
159+
This isn't a playground in the same sense as the official Vue playground. Instead, it's just an application that is pre-configured to be able to use your library.
160+
161+
The playground application will use your library direct from the source code, without needing to build the library separately. This is usually beneficial, as it allows for quicker development and immediate feedback on changes. But it does make the playground slightly less representative of a real consuming application, as it isn't using the built files.
162+
163+
## Include example code?{#include-examples}
164+
165+
:::info NOTE
166+
This question is only asked when using the `--extended` flag.
167+
:::
168+
169+
The example code includes some sample components and mock documentation pages. These are useful for testing that the newly created project actually works.
170+
171+
But if you've used the tool before and already know what you're doing, the examples can sometimes be a nuisance, as you're just going to immediately delete them. This option allows you to skip including them in the first place, but at the expense of creating a project that won't actually build because there's no code to build.
172+
173+
## Configure `@` as an alias for `src`?{#configure-src-alias}
174+
175+
:::info NOTE
176+
This question is only asked when using the `--extended` flag.
177+
:::
178+
179+
The official [`create-vue`](https://github.com/vuejs/create-vue) tool configures an alias called `@` that resolves to `src`. This can be useful in large applications with deeply nested directory structures, rather than trying to use `../../../..` at the start of relative paths.
180+
181+
This is typically less useful in libraries, as there tend to be fewer files and less nesting, so using an alias is usually unnecessary.
182+
183+
But if you do want to use an alias, it can be tricky to configure it in a way that works across the various internal packages (e.g. the docs and playground). Selecting this option will configure that for you.
184+
185+
If you want to use other aliases for directories in your library, rather than `@`, you may still want to select this option as a starting point.
186+
187+
## Configure global `__TEST__` variable?{#configure-test-variable}
188+
189+
:::info NOTE
190+
This question is only asked when using the `--extended` flag.
191+
:::
192+
193+
All projects created with this tool include a global variable called `__DEV__` that can be used to conditionally run code in either development or production. This is typically used to include extra warning messages to help consumers during development.
194+
195+
Optionally, you can also include a global variable called `__TEST__`, which allows you to detect when code is running in tests.
196+
197+
While this is occasionally useful, it is much less commonly used than `__DEV__`, so configuration for `__TEST__` is optional.
198+
199+
While `__DEV__` and `__TEST__` are exposed as global variables in the code and TypeScript types, they are actually statically replaced by Vite, so the variables are already gone by the time the code runs.

0 commit comments

Comments
 (0)