{"id":11032,"library":"hexo-server","title":"Hexo Development Server","description":"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.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/hexojs/hexo-server","tags":["javascript","hexo","server","connect"],"install":[{"cmd":"npm install hexo-server","lang":"bash","label":"npm"},{"cmd":"yarn add hexo-server","lang":"bash","label":"yarn"},{"cmd":"pnpm add hexo-server","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency for serving static files, configurable via `serveStatic` option.","package":"serve-static","optional":false},{"reason":"Peer dependency; this is a plugin for the Hexo static site generator.","package":"hexo","optional":false}],"imports":[{"note":"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.","wrong":"import pluginInit from 'hexo-server';","symbol":"pluginInit","correct":"const pluginInit = require('hexo-server');\n// hexo.init(); // Assuming hexo instance is available\n// pluginInit(hexo); // This is how Hexo's core registers the plugin"},{"note":"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.","wrong":"import { startServerCommand } from 'hexo-server';","symbol":"startServerCommand","correct":"const startServerCommand = require('hexo-server/lib/server');\n// To run programmatically, you'd need a Hexo instance:\n// const hexo = require('hexo');\n// const instance = new hexo(process.cwd());\n// instance.init().then(() => startServerCommand(instance.args));"},{"note":"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.","wrong":"import { ServerOptions } from 'hexo-server';","symbol":"ServerOptions","correct":null}],"quickstart":{"code":"const { spawn } = require('child_process');\nconst path = require('path');\nconst fs = require('fs');\n\n// Ensure Hexo is installed globally or locally\n// For a quickstart, we'll assume a hexo project exists\n\nconst hexoProjectPath = path.join(__dirname, 'my-hexo-blog');\n\n// Create a dummy Hexo project for demonstration if it doesn't exist\nif (!fs.existsSync(hexoProjectPath)) {\n  console.log('Creating a dummy Hexo blog for demonstration...');\n  // This would typically be `hexo init my-hexo-blog`\n  fs.mkdirSync(hexoProjectPath);\n  fs.writeFileSync(path.join(hexoProjectPath, '_config.yml'), 'title: My Hexo Blog\\nport: 4000\\n');\n  fs.mkdirSync(path.join(hexoProjectPath, 'source'));\n  fs.writeFileSync(path.join(hexoProjectPath, 'source', 'index.md'), '---\\ntitle: Hello World\\n---');\n  console.log('Dummy Hexo blog created.');\n}\n\n// Start the Hexo server from within the project directory\nconsole.log(`Starting Hexo server for project: ${hexoProjectPath}`);\nconst hexoServerProcess = spawn('hexo', ['server', '-p', '4001', '-i', '127.0.0.1'], {\n  cwd: hexoProjectPath,\n  stdio: 'inherit',\n  shell: true // Required on Windows for 'hexo' command to be found\n});\n\nhexoServerProcess.on('error', (err) => {\n  console.error('Failed to start Hexo server:', err);\n});\n\nhexoServerProcess.on('exit', (code) => {\n  console.log(`Hexo server exited with code ${code}`);\n});\n\n// Keep the process alive for a few seconds to demonstrate, then exit\nsetTimeout(() => {\n  console.log('Stopping Hexo server after 10 seconds...');\n  hexoServerProcess.kill(); // Terminate the child process\n}, 10000);\n","lang":"javascript","description":"Demonstrates how to start the Hexo development server for a given project directory using the Hexo CLI, including basic project setup."},"warnings":[{"fix":"Upgrade Node.js to version 12.13.0 or higher (e.g., using nvm, fnm, or Volta).","message":"Version 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.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Upgrade Node.js to version 10.x or higher.","message":"Version 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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Upgrade Node.js to version 8.x or higher.","message":"Version 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.","severity":"breaking","affected_versions":">=1.0.0"},{"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`).","message":"The 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.","severity":"gotcha","affected_versions":">=0.3.1"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=2.0.0"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=0.x"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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`.","cause":"The default port 4000 (or your configured port) is already being used by another application on your system.","error":"Error: listen EADDRINUSE: address already in use :::4000"},{"fix":"Run `npm install hexo-server --save` in your Hexo project directory.","cause":"The `hexo-server` package is not installed in your project's `node_modules` directory.","error":"Error: Cannot find module 'hexo-server'"},{"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`.","cause":"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.","error":"TypeError [ERR_INVALID_ARG_TYPE]: The \"url\" argument must be of type string. Received undefined"}],"ecosystem":"npm"}