vuepress

library1.9.10jsnpmunverified

VuePress 1.x is a Vue-powered static site generator designed primarily for technical documentation. It enables authors to write content in Markdown and embed Vue components directly within it, offering a flexible and interactive documentation experience. The current stable version is 1.9.10, released in August 2023. Key differentiators include its Vue component-based layout system, a powerful plugin API for extending functionality, and a theming system. Since version 1.9.0, it features full TypeScript support for configuration files, and since 1.9.2, for plugins and themes, enhancing developer experience with type inference. While 1.x receives occasional bug fixes, it is officially in maintenance mode, with the core team's focus shifted to VuePress 2.x (which uses Vue 3 and ESM) and the even lighter-weight VitePress.

web-framework

npm install vuepress

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · VUEPRESS

vuepress

web-frameworkjavascriptv1.9.10

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

defineConfig

✓ import { defineConfig } from 'vuepress/config'

✗ const { defineConfig } = require('vuepress/config')

Used in `.vuepress/config.ts` for type inference and helper functions. CommonJS `require` is not supported in VuePress 2.x and discouraged for new 1.x TypeScript configurations.

defineConfig4CustomTheme

✓ import { defineConfig4CustomTheme } from 'vuepress/config'

Specifically for providing type inference for custom theme configurations in `.vuepress/config.ts`.

ClientOnly

✓ <ClientOnly><NonSSRFriendlyComponent/></ClientOnly>

A built-in component used directly in Markdown or Vue templates to ensure that its content is rendered only on the client side, preventing SSR mismatches for browser-specific components or libraries.

Demonstrates setting up a basic VuePress 1.x project, including package.json scripts, a TypeScript-based configuration file (`config.ts`) with navigation and sidebar, and a sample Markdown page using a built-in component.

{ "name": "my-docs", "version": "1.0.0", "description": "My awesome VuePress documentation", "main": "index.js", "scripts": { "docs:dev": "vuepress dev docs", "docs:build": "vuepress build docs" }, "keywords": [], "author": "", "license": "MIT", "devDependencies": { "vuepress": "^1.9.10", "@vuepress/theme-default": "^1.9.10" } } // docs/.vuepress/config.ts import { defineConfig } from 'vuepress/config'; export default defineConfig({ title: 'Hello VuePress 1.x', description: 'Just playing around', themeConfig: { nav: [ { text: 'Home', link: '/' }, { text: 'Guide', link: '/guide/' }, { text: 'External', link: 'https://vuejs.org' } ], sidebar: [ '/', '/guide/' ] } }); // docs/README.md --- layout: home --- # Hello VuePress! This is my first VuePress 1.x site. <ClientOnly> <p>This paragraph only renders on the client side.</p> </ClientOnly>

vuepress --version

Debug

Known issues

breakingVuePress 1.x is in maintenance mode and not actively developed. VuePress 2.x (based on Vue 3 and pure ESM) introduces significant breaking changes and is not backward compatible. Users are encouraged to consider migrating to VuePress 2.x or VitePress for new projects or long-term maintenance.

fix

For new projects, consider `npm init vuepress@next` for VuePress 2.x or `npm init vitepress` for VitePress. For existing 1.x projects, consult the VuePress 2.x migration guide for breaking changes in APIs, configuration, and plugin/theme compatibility.

affects: >=1.0.0

breakingVuePress 2.x removes support for CommonJS configuration files. All configurations (e.g., `.vuepress/config.js`) must be refactored to ESM (`.vuepress/config.ts` or `.vuepress/config.mjs`) when migrating.

fix

Convert `module.exports = { ... }` to `import { defineConfig } from 'vuepress'; export default defineConfig({ ... })` and rename `.js` files to `.ts` or `.mjs`.

affects: >=1.0.0

gotchaLarge VuePress 1.x sites, especially with many pages or complex processing, can suffer from `FATAL ERROR: JavaScript heap out of memory` during the build process due to Webpack's memory consumption and VuePress 1.x's inefficiency with file handling.

fix

Increase Node.js memory limit (e.g., `NODE_OPTIONS=--max_old_space_size=8192 vuepress build docs`). Consider optimizing the site structure, reducing the number of generated files, or migrating to VuePress 2.x, which uses Webpack 5/Vite and is generally more efficient.

affects: >=1.0.0

gotchaCustom Vue components used directly in Markdown files must adhere to Vue's component naming conventions (PascalCase or contain a hyphen). Failure to do so can cause them to be treated as inline HTML elements and wrapped in `<p>` tags, leading to client-side hydration mismatches.

fix

Ensure all custom components have names like `<MyComponent>` or `<my-component>`. If a component is expected to render differently on client/server or accesses browser-specific APIs, wrap it in `<ClientOnly>` component.

affects: >=1.0.0

gotchaVuePress 1.x uses Stylus internally, meaning you do not need to install `stylus` and `stylus-loader` for basic styling. However, for other CSS pre-processors, you must manually extend the internal Webpack config and install the necessary dependencies.

fix

For Stylus, just write your `.styl` files. For other pre-processors (e.g., Sass, Less), refer to the VuePress advanced configuration guide to extend Webpack rules and install corresponding loaders (e.g., `sass-loader`, `node-sass`).

affects: >=1.0.0

Errors

Common errors & fixes

FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory

VuePress 1.x build process consumes excessive memory, especially for large sites, leading to Node.js hitting its heap limit.

fix

Increase Node.js memory allocation for the build command: `NODE_OPTIONS=--max_old_space_size=8192 yarn docs:build` (adjust size as needed, e.g., 4096, 12048).

[Vue warn]: Failed to resolve component: XXX

Using non-standard or deprecated HTML tags (e.g., `<center>`, `<font>`) in Markdown or Vue templates that Vue.js does not recognize as valid components or elements.

fix

Replace non-standard HTML tags with modern, semantic HTML5 elements and CSS for styling. Use the `--debug` flag during development (`vuepress dev docs --debug`) to get warning logs about unrecognized tags.

warning Overriding existing page xxx

Two or more Markdown files in the project resolve to the same URL path, causing one to overwrite the other during compilation. Common examples are `a/b.md` and `a/b/README.md`.

fix

Review your file structure and ensure each Markdown file has a unique URL path. Adjust directory structure or file names to avoid path conflicts. For example, use `a/b.md` OR `a/b/index.md`, but not both if they map to the same `/a/b/` URL.

Hydration completed but contains mismatches

Server-side rendered (SSR) HTML differs from the client-side rendered content. This can be caused by external services like CloudFlare's static resource compression, or Vue components rendering differently on the server vs. client.

fix

If using CloudFlare, disable 'Auto Minify' for JavaScript and HTML. For components that behave differently, wrap them in VuePress's `<ClientOnly />` component. Set `__VUE_PROD_HYDRATION_MISMATCH_DETAILS__ = true` in development for detailed browser console errors.

Upgrade

Version history

1.9.10latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

7 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/vuejs/vuepress ↗

packagehttps://www.npmjs.com/package/vuepress ↗

homepagehttps://vuepress.vuejs.org ↗