Registry / web-framework / hexo-server

hexo-server

JSON →
library3.0.0jsnpmunverified

hexo-server is the official server module for the static site generator Hexo. It provides a local development server to preview Hexo sites during development. Currently at stable version 3.0.0, it follows Hexo's release cadence, often aligning major version bumps with Node.js End-of-Life cycles. Key differentiators include its tight integration with the Hexo ecosystem, automatic recompilation of site assets on changes, and configurable options for port, IP, logging, and static file serving. It uses a Connect/Express-like middleware stack to serve generated files and handle live reloading, making it an essential tool for Hexo developers.

npm install hexo-server
INSTALL
IMPORT
SIG · HEXO-SERVER
H
hexo-server
web-frameworkjavascriptv3.0.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

pluginInit
const pluginInit = require('hexo-server'); // hexo.init(); // Assuming hexo instance is available // pluginInit(hexo); // This is how Hexo's core registers the plugin
import pluginInit from 'hexo-server';
This package is primarily a Hexo plugin, and its main export is a function for Hexo's internal use to register the `server` command. Direct programmatic use by end-users is uncommon; it's mostly invoked via the `hexo server` CLI command. It is a CommonJS module.
startServerCommand
const startServerCommand = require('hexo-server/lib/server'); // To run programmatically, you'd need a Hexo instance: // const hexo = require('hexo'); // const instance = new hexo(process.cwd()); // instance.init().then(() => startServerCommand(instance.args));
import { startServerCommand } from 'hexo-server';
This is the internal function executed when `hexo server` is run via the CLI. Directly importing it bypasses Hexo's plugin registration and is generally not recommended as it's an internal implementation detail.
ServerOptions
import { ServerOptions } from 'hexo-server';
This package does not expose specific types or named exports for server options or other components for public consumption. Configuration is typically done via `_config.yml` or CLI arguments.

Demonstrates how to start the Hexo development server for a given project directory using the Hexo CLI, including basic project setup.

const { spawn } = require('child_process'); const path = require('path'); const fs = require('fs'); // Ensure Hexo is installed globally or locally // For a quickstart, we'll assume a hexo project exists const hexoProjectPath = path.join(__dirname, 'my-hexo-blog'); // Create a dummy Hexo project for demonstration if it doesn't exist if (!fs.existsSync(hexoProjectPath)) { console.log('Creating a dummy Hexo blog for demonstration...'); // This would typically be `hexo init my-hexo-blog` fs.mkdirSync(hexoProjectPath); fs.writeFileSync(path.join(hexoProjectPath, '_config.yml'), 'title: My Hexo Blog\nport: 4000\n'); fs.mkdirSync(path.join(hexoProjectPath, 'source')); fs.writeFileSync(path.join(hexoProjectPath, 'source', 'index.md'), '---\ntitle: Hello World\n---'); console.log('Dummy Hexo blog created.'); } // Start the Hexo server from within the project directory console.log(`Starting Hexo server for project: ${hexoProjectPath}`); const hexoServerProcess = spawn('hexo', ['server', '-p', '4001', '-i', '127.0.0.1'], { cwd: hexoProjectPath, stdio: 'inherit', shell: true // Required on Windows for 'hexo' command to be found }); hexoServerProcess.on('error', (err) => { console.error('Failed to start Hexo server:', err); }); hexoServerProcess.on('exit', (code) => { console.log(`Hexo server exited with code ${code}`); }); // Keep the process alive for a few seconds to demonstrate, then exit setTimeout(() => { console.log('Stopping Hexo server after 10 seconds...'); hexoServerProcess.kill(); // Terminate the child process }, 10000);
hexo --version
Debug
Known issues
breakingVersion 3.0.0 drops support for Node.js 10.x. Users on Node.js 10 must upgrade their Node.js environment to 12.13.0 or higher, or remain on hexo-server v2.x.
fix
Upgrade Node.js to version 12.13.0 or higher (e.g., using nvm, fnm, or Volta).
affects: >=3.0.0
breakingVersion 2.0.0 drops support for Node.js 8.x. Users on Node.js 8 must upgrade their Node.js environment to 10.x or higher, or remain on hexo-server v1.x.
fix
Upgrade Node.js to version 10.x or higher.
affects: >=2.0.0
breakingVersion 1.0.0 drops support for Node.js 6.x. Users on Node.js 6 must upgrade their Node.js environment to 8.x or higher.
fix
Upgrade Node.js to version 8.x or higher.
affects: >=1.0.0
gotchaThe default server IP configuration changed across versions. In 0.3.1 and later, it listens on all interfaces (`::` or `0.0.0.0`). Earlier versions might have different defaults, potentially causing connectivity issues if not explicitly set.
fix
If experiencing connectivity issues, explicitly set the `--ip` flag or `ip` option in `_config.yml` (e.g., `hexo server -i 0.0.0.0`).
affects: >=0.3.1
gotchaThe `pretty_urls` configuration, particularly `trailing_index: false`, combined with serving pages ending in `.html`, can cause 301 redirects in v2.0.0. If you rely on exact URL paths for pages ending in `.html`, this behavior change might impact SEO or internal linking.
fix
Review your `pretty_urls` configuration in `_config.yml` or explicitly set `trailing_index: true` if you prefer direct access to `.html` paths without redirects when pretty URLs are enabled.
affects: >=2.0.0
gotchaThe `cache` option, when set to `true`, can significantly speed up server responses but will prevent changes to your Hexo source files from being reflected in real-time. This setting is primarily for production environments or scenarios where live reloading is not required.
fix
Ensure `cache: false` in your `_config.yml` (or omit it, as `false` is the default) during development to enable live reloading and see changes immediately. Set to `true` only for performance in a static serving context.
affects: >=0.x
Errors
Common errors & fixes
Error: listen EADDRINUSE: address already in use :::4000
The default port 4000 (or your configured port) is already being used by another application on your system.
fix
Specify a different port using the `-p` or `--port` CLI option (e.g., `hexo server -p 5000`) or configure it in your Hexo `_config.yml`.
Error: Cannot find module 'hexo-server'
The `hexo-server` package is not installed in your project's `node_modules` directory.
fix
Run `npm install hexo-server --save` in your Hexo project directory.
TypeError [ERR_INVALID_ARG_TYPE]: The "url" argument must be of type string. Received undefined
Potentially related to internal URL parsing logic, particularly in older Node.js versions or during specific internal refactors (like the `url.format` replacement in v3.0.0) if incompatible arguments are passed.
fix
Ensure your Node.js version meets the minimum requirement (`>=12.13.0` for v3.0.0). If occurring during server startup, check Hexo configuration for malformed URL-related settings. If using older versions, this might be a bug fixed in newer releases, so upgrade `hexo-server`.
Upgrade
Version history
3.0.0latest on npm
Audit
Dependencies
serve-staticrequiredCore dependency for serving static files, configurable via `serveStatic` option.
hexorequiredPeer dependency; this is a plugin for the Hexo static site generator.
Agent activity
6 hits · last 30 days
node
6
Resources