VuePress

# Local Development

# Introduction

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!

# Prerequisites

*Node.js v10 should work as well, but other versions have not been verified.

# Setup Guide

In this guide, we will be using the following names to refer to the two projects you need to be successful:

  • VuePress Project: This refers to your fork of the official VuePress repository (opens new window)
  • 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

# VuePress Project Setup

  1. Fork the official VuePress repository (opens new window)
  2. Clone your fork onto your machine (e.g., git clone ...)
  3. Open your cloned project in a new terminal window
  4. Run the following commands:
# Install all dependencies in the project
yarn

# Compile shared-utils TypeScript package into JavaScript
yarn tsc
  1. Verify there is no global installation of VuePress
# Check global yarn packages
yarn global list

# If it exists, remove global VuePress package
yarn global remove vuepress
  1. Configure local VuePress Project to be the source of truth
# Registers local VuePress project
yarn register-vuepress

# If successful, you should see a message
# like `success Registered "vuepress"`

And with that, we’re ready to setup our VuePress Sandbox!

# VuePress Sandbox Setup

  1. In a separate terminal, create a new npm project.
# Create a new folder
mkdir vuepress-sandbox

# Change directory to VuePress Sandbox
cd vuepress-sandbox

# Initalize a new npm project
yarn init # or npm init

# You will be prompted to fill out a form
# Since this is a sandbox environment,
# feel free to just hit skip through it
# by hitting enter until it completes setup!
  1. Create a basic VuePress Sandbox site
# Create the folder where your site will live
mkdir docs

# Initialize it with a simple markdown file
echo '# My VuePress Sandbox Site' > docs/index.md
  1. Add a script to package.json to start VuePress environment






 







{
  "name": "vuepress-sandbox",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "dev": "vuepress dev docs",
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "ISC",
  "dependencies": {}
}
  1. Verify that the script does not work
# Run dev command
yarn dev

# You should receive an error indicating
# that VuePress cannot be found.
# This is a good thing!
  1. Link your VuePress Project to your VuePress Sandbox
# Link VuePress Project
yarn link vuepress

# You should see a message like
# `success Using linked package for "vuepress"`
  1. Run your script again and it should work!
# Start local dev environment
yarn dev

And with that, you should have a fully functioning local VuePress development environment!

# Disable Local Development

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:

  1. Navigate to your VuePress Project in the terminal
  2. Unregister your VuePress Project
# Unregister VuePress Project
yarn unregister-vuepress
  1. Navigate to your VuePress Sandbox in the terminal
  2. Remove dependency on local VuePress Project
yarn unlink vuepress

And that’s it! You can go back to regular development now!

# Notes

  • yarn will use hoisting. What does it mean for you ?
    • It will regroup all dependencies in the workspace root and link all packages.
  • 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.
  • There is a special package you should have a look is @vuepress/shared-utils that are in TypeScript.
    • 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
  • You will have interesting commands available: