You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: packages/docs/docs/miscellaneous/local-development.md
+123-51
Original file line number
Diff line number
Diff line change
@@ -4,96 +4,168 @@ sidebar: auto
4
4
5
5
# Local Development
6
6
7
-
## Information
7
+
## Introduction
8
8
9
-
If you here you may be interested in improving core VuePress.
9
+
When it comes to contributing to an open-source project, the biggest obstacle people encounter is trying to get a local environment setup so they can test their changes to make sure everything works as expected. As a result, we have written this guide to help you so you can begin contributing to the VuePress ecosystem!
10
10
11
-
VuePress is using a combo with [Yarn workspaces](https://yarnpkg.com/lang/en/docs/workspaces/) and [Lerna](https://github.com/lerna/lerna).
11
+
## Prerequisites
12
12
13
-
## Init packages
13
+
-[Node.js v12.x](https://nodejs.org/en/)\*
14
+
-[Yarn v1.x](https://classic.yarnpkg.com/)
15
+
16
+
\*Node.js v10 should work as well, but other versions have not been verified.
17
+
18
+
## Setup Guide
19
+
20
+
In this guide, we will be using the following names to refer to the two projects you need to be successful:
21
+
22
+
-**VuePress Project**: This refers to your fork of the [official VuePress repository](https://github.com/vuejs/vuepress/)
23
+
-**VuePress Sandbox**: This refers to a local instance of VuePress that will serve as the simulation for creating test scenarios to verify that changes in the VuePress Project work as expected
24
+
25
+
### VuePress Project Setup
26
+
27
+
1. Fork the [official VuePress repository](https://github.com/vuejs/vuepress/)
28
+
1. Clone your fork onto your machine (e.g., `git clone ...`)
29
+
1. Open your cloned project in a new terminal window
30
+
1. Run the following commands:
14
31
15
32
```bash
16
-
yarn // it will install dependencies of all packages
33
+
# Install all dependencies in the project
34
+
yarn
35
+
36
+
# Compile shared-utils TypeScript package into JavaScript
37
+
yarn tsc
17
38
```
18
39
19
-
`yarn` will use hoisting. What does it mean for you ?
40
+
5. Verify there is no global installation of VuePress
20
41
21
-
It will regroup all dependencies in the workspace root and link all packages.
42
+
```bash
43
+
# Check global yarn packages
44
+
yarn global list
22
45
23
-
Check the link by running the following command:
46
+
# If it exists, remove global VuePress package
47
+
yarn global remove vuepress
48
+
```
49
+
50
+
6. Configure local VuePress Project to be the source of truth
24
51
25
52
```bash
26
-
ls -la node_modules/@vuepress
53
+
# Registers local VuePress project
54
+
yarn register-vuepress
55
+
56
+
# If successful, you should see a message
57
+
# like `success Registered "vuepress"`
27
58
```
28
59
29
-
:::warning
30
-
You have to take care to declare all dependencies inside subFolders package.json. When publish the lib if dependencies from a package is not declare it will just not work.
31
-
:::
60
+
And with that, we’re ready to setup our VuePress Sandbox!
32
61
33
-
:::warning
34
-
There is a special package you should have a look is @vuepress/shared-utils that are in typescript.
35
-
:::
62
+
### VuePress Sandbox Setup
36
63
37
-
After install everything it will run `yarn tsc`. This command will tell to @vuepress/shared-utils workspace to compile his js.
64
+
1. In a separate terminal, create a new npm project.
38
65
39
-
:::warning
40
-
From here if you are making change inside this package you will have to
41
-
run `yarn tsc` all the time or run in separate shell `yarn run tsc -w`. This will re run tsc at any change from shared-utils
42
-
:::
66
+
```bash
67
+
# Create a new folder
68
+
mkdir vuepress-sandbox
43
69
44
-
## Link
70
+
# Change directory to VuePress Sandbox
71
+
cd vuepress-sandbox
45
72
46
-
Good from here you have everything ready. You need to link VuePress to your project.
73
+
# Initalize a new npm project
74
+
yarn init # or npm init
47
75
48
-
```bash
49
-
yarn register-vuepress
76
+
# You will be prompted to fill out a form
77
+
# Since this is a sandbox environment,
78
+
# feel free to just hit skip through it
79
+
# by hitting enter until it completes setup!
50
80
```
51
81
52
-
You will have something like this: `success Registered "vuepress".`
82
+
2. Create a basic VuePress Sandbox site
53
83
54
-
It will link the package VuePress from `packages/vuepress`. You will have access to VuePress cli and packages.
84
+
```bash
85
+
# Create the folder where your site will live
86
+
mkdir docs
55
87
56
-
They are declared in the `packages/vuepress/package.json`
88
+
# Initialize it with a simple markdown file
89
+
echo'# My VuePress Sandbox Site'> docs/index.md
90
+
```
57
91
58
-
```js
92
+
3. Add a script to `package.json` to start VuePress environment
93
+
94
+
```json{7}
59
95
{
60
-
"main":"index.js",
61
-
///
62
-
"bin": {
63
-
"vuepress":"cli.js"
64
-
}
65
-
///
96
+
"name": "vuepress-sandbox",
97
+
"version": "1.0.0",
98
+
"description": "",
99
+
"main": "index.js",
100
+
"scripts": {
101
+
"dev": "vuepress dev docs",
102
+
"test": "echo \"Error: no test specified\" && exit 1"
103
+
},
104
+
"author": "",
105
+
"license": "ISC",
106
+
"dependencies": {}
66
107
}
67
108
```
68
109
69
-
Now go to your project and run `yarn link vuepress`.
110
+
4. Verify that the script does not work
70
111
71
-
You should have it `success Using linked package for "vuepress".`
112
+
```bash
113
+
# Run dev command
114
+
yarn dev
72
115
73
-
## Unlink
116
+
# You should receive an error indicating
117
+
# that VuePress cannot be found.
118
+
# This is a good thing!
119
+
```
74
120
75
-
You may want to unlink everything. For it in the workspace root folder. Run
121
+
5. Link your VuePress Project to your VuePress Sandbox
76
122
77
123
```bash
78
-
yarn unregister-vuepress
124
+
# Link VuePress Project
125
+
yarn link vuepress
126
+
127
+
# You should see a message like
128
+
# `success Using linked package for "vuepress"`
129
+
```
130
+
131
+
6. Run your script again and it should work!
132
+
133
+
```bash
134
+
# Start local dev environment
135
+
yarn dev
79
136
```
80
137
81
-
Now you can run `yarn unlink vuepress` into your project folder.
138
+
And with that, you should have a fully functioning local VuePress development environment!
139
+
140
+
### Disable Local Development
82
141
83
-
If everything work properly you should have an error telling you there is no package found called vuepress, if you run `yarn link vuepress` in you project folder.
142
+
While it’s great that you can work with a local instance of VuePress, there will be times that you want to disable it so that you can refer to the published version instead. To do this, you will need to do the following:
84
143
85
-
## BUGS / QA
144
+
1. Navigate to your VuePress Project in the terminal
145
+
1. Unregister your VuePress Project
146
+
147
+
```bash
148
+
# Unregister VuePress Project
149
+
yarn unregister-vuepress
150
+
```
86
151
87
-
You will maybe find some difficulty with link. If you encounter something like `There's already a package called "vuepress" registered`.
88
-
You already have VuePress registered:
152
+
3. Navigate to your VuePress Sandbox in the terminal
153
+
1. Remove dependency on local VuePress Project
89
154
90
-
- If you already link VuePress from [Link](#link). It’s totally fine. If you make changes because it is symlink you dont have to re run something. You will have to rerun yarn tsc if you update shared-utils package. Nothing more
91
-
- If you didn’t do anything. You already have VuePress linked somewhere. What you have to do is deleting folder where you ran `yarn link` or `yarn unlink`.
155
+
```bash
156
+
yarn unlink vuepress
157
+
```
92
158
93
-
## More
159
+
And that’s it! You can go back to regular development now!
94
160
95
-
You will have interesting commands available:
161
+
## Notes
96
162
97
-
-`yarn packages:list` will list you every packages present and their versions [More...](https://github.com/lerna/lerna/tree/master/commands/list#readme)
98
-
-`yarn packages:changed` will tell you which package will be affect by the next lerna publish / version [More...](https://github.com/lerna/lerna/tree/master/commands/changed#readme)
99
-
-`yarn packages:diff` will show you all diff from last release [More...](https://github.com/lerna/lerna/tree/master/commands/diff#readme)
163
+
-`yarn` will use hoisting. What does it mean for you ?
164
+
- It will regroup all dependencies in the workspace root and link all packages.
165
+
- You have to take care to declare all dependencies inside subFolders package.json. When publish the lib if dependencies from a package is not declare it will just not work.
166
+
- There is a special package you should have a look is @vuepress/shared-utils that are in TypeScript.
167
+
- From here if you are making change inside this package you will have to run `yarn tsc` all the time or run in separate shell `yarn run tsc -w`. This will re run tsc at any change from shared-utils
168
+
- You will have interesting commands available:
169
+
-`yarn packages:list` will list you every packages present and their versions [More...](https://github.com/lerna/lerna/tree/master/commands/list#readme)
170
+
-`yarn packages:changed` will tell you which package will be affect by the next lerna publish / version [More...](https://github.com/lerna/lerna/tree/master/commands/changed#readme)
171
+
-`yarn packages:diff` will show you all diff from last release [More...](https://github.com/lerna/lerna/tree/master/commands/diff#readme)
0 commit comments