Hexo Development Server

Common errors

• Error: listen EADDRINUSE: address already in use :::4000

  cause 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'

  cause 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

  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.
  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`.

Warnings

• breaking 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.
  Fix: Upgrade Node.js to version 12.13.0 or higher (e.g., using nvm, fnm, or Volta).
• breaking 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.
  Fix: Upgrade Node.js to version 10.x or higher.
• breaking 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.
  Fix: Upgrade Node.js to version 8.x or higher.
• gotcha 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.
  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`).
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install hexo-server npm
• yarn add hexo-server yarn
• pnpm add hexo-server pnpm

Imports

• pluginInit
  wrong:

  import pluginInit from 'hexo-server';

  correct:

  const pluginInit = require('hexo-server');
  // hexo.init(); // Assuming hexo instance is available
  // pluginInit(hexo); // This is how Hexo's core registers the plugin

  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
  wrong:

  import { startServerCommand } from 'hexo-server';

  correct:

  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));

  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
  wrong:

  import { ServerOptions } from 'hexo-server';

  correct:
  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.

Quickstart

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);