{"id":13282,"library":"harp","title":"Harp Static Web Server","description":"Harp is a zero-configuration static web server, generator, and bundler for Node.js. It implicitly pre-processes a wide range of web assets, including Jade, Markdown, EJS, Less, Stylus, Sass, SCSS, CoffeeScript, JSX, and CJS, converting them into HTML, CSS, and JavaScript. The current stable version is 0.47.2, with recent releases primarily focusing on critical security patches and maintenance rather than new feature development, indicating a mature but less actively evolving project. Harp differentiates itself by offering a simple, fast, and lightweight solution that aims to avoid complex build steps or task runners. It features first-class layout and partial support, intelligent path redirects, and the crucial ability to export an entire project to static assets for easy deployment. It also includes implicit vendor prefixing for CSS preprocessors via Autoprefixer. Harp is ideal for publishing simple front-ends with minimal setup and low cognitive overhead, positioning itself as an alternative to heavier web frameworks.","status":"maintenance","version":"0.47.2","language":"javascript","source_language":"en","source_url":"https://github.com/sintaxi/harp","tags":["javascript","static web server","static site generator","sass","markdown","jade","ejs","cjs","jsx"],"install":[{"cmd":"npm install harp","lang":"bash","label":"npm"},{"cmd":"yarn add harp","lang":"bash","label":"yarn"},{"cmd":"pnpm add harp","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Harp is primarily a CommonJS module and does not natively support ES module `import` syntax. The main `harp` object provides server and compilation methods.","wrong":"import harp from 'harp'","symbol":"harp","correct":"const harp = require('harp')"},{"note":"The server functionality is accessed as a method on the default `harp` object, not as a named export. Ensure the module is imported via `require` first.","wrong":"import { server } from 'harp'","symbol":"harp.server","correct":"const harp = require('harp');\nharp.server(__dirname);"},{"note":"The compilation functionality is accessed as a method on the default `harp` object, not as a named export. It's a callback-based API for completion.","wrong":"import { compile } from 'harp'","symbol":"harp.compile","correct":"const harp = require('harp');\nharp.compile(__dirname, './dist', () => console.log('Compiled!'));"}],"quickstart":{"code":"#!/bin/bash\n\n# Install Harp globally\nnpm install -g harp\n\n# Create a new project directory\nmkdir harp-project\ncd harp-project\n\n# Create a basic Jade template\necho \"doctype html\\nhtml\\n  head\\n    title My Harp Site\\n    link(rel='stylesheet', href='/main.css')\\n  body\\n    h1 Welcome to Harp!\\n    p This is a zero-configuration static site.\" > index.jade\n\n# Create a simple SCSS stylesheet\necho \"body { font-family: sans-serif; h1 { color: #333; } }\" > main.scss\n\n# Create _harp.json for potential configuration (e.g., basicAuth)\necho '{ \"globals\": { \"siteName\": \"My Harp Project\" } }' > _harp.json\n\necho \"\\n--- Starting Harp server ---\\nAccess at http://localhost:9000\\n\"\n# Start the Harp server in the background\nharp . & \nSERVER_PID=$!\n\n# Wait a moment for the server to start\nsleep 3\n\necho \"\\n--- Compiling project to static assets ---\\n\"\n# Compile the project to a 'www' directory\nharp . www\n\necho \"\\n--- Compiled project available in 'www' directory ---\\n\"\n# Clean up server process\nkill $SERVER_PID\n\necho \"\\nTo view compiled site: cd www && python -m http.server 8000\\nTo restart dev server: harp .\"\n","lang":"bash","description":"Installs Harp globally, creates a new project with a Jade template and SCSS stylesheet, starts the development server, and then compiles the project to static assets."},"warnings":[{"fix":"Upgrade to `harp@0.40.2` or later immediately. Ensure all deployments use a patched version.","message":"Versions prior to `0.40.2` are vulnerable to 'Unauthorized File Access via encoded underscore' (CVE-2019-10779), allowing attackers to access arbitrary files. This is a critical security vulnerability.","severity":"breaking","affected_versions":"<0.40.2"},{"fix":"Review your project for implicit symlink usage. If symlinks are essential, consider restructuring your project or carefully using the `--deny-symlinks` flag with appropriate security considerations.","message":"Starting from `v0.40.3`, Harp introduced a `--deny-symlinks` flag. If your project relied on serving symlinks, they will now result in a 'Forbidden' response unless this flag is explicitly managed.","severity":"breaking","affected_versions":">=0.40.3"},{"fix":"Ensure Harp is used within a CommonJS environment or project. If integrating with ESM, consider using a CJS wrapper or bundler that correctly handles CJS dependencies.","message":"Harp is primarily a CommonJS library and does not officially support ES Modules (`import/export` syntax). Attempting to use it in an ESM context will lead to runtime errors.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Avoid using `harp@0.20.2`. If you are on this version, upgrade to `v0.20.3` or any later stable version to resolve these issues.","message":"Specific versions, notably `v0.20.2`, introduced critical bugs such as address binding errors when starting the server and RangeErrors during compilation, which were fixed in `v0.20.3`.","severity":"gotcha","affected_versions":"0.20.2"},{"fix":"Refer to Harp's `package.json` for recommended Node.js versions. If encountering issues, try running with Node.js LTS versions (e.g., Node 16 or 18 at the time of v0.47.2's release) or check specific preprocessor library compatibility.","message":"While Harp has broad Node.js compatibility (`>=6.x`), its ecosystem dependencies (like `node-sass`, `jade`) may have their own compatibility constraints. Running Harp with very new or very old Node.js versions might encounter build issues or require specific dependency versions.","severity":"gotcha","affected_versions":">=0.1.0"}],"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 `harp --port <new_port>` or `harp -p <new_port>`. Ensure no other processes are running on the desired port.","cause":"The default port 9000 is already in use by another process, or a Harp server was not properly shut down.","error":"Error: listen EADDRINUSE :::9000"},{"fix":"Restructure your project to avoid symlinks for publicly served files, or if you understand the security implications, verify Harp's documentation for overriding this behavior (if available, generally not recommended).","cause":"Harp is attempting to serve a file that is a symbolic link, and the `--deny-symlinks` flag is active (default since v0.40.3).","error":"Forbidden"},{"fix":"Ensure your project is configured as a CommonJS module (`'type': 'commonjs'` in `package.json` or by not specifying `type` for older Node.js versions) when using Harp, or use a tool like Webpack to bundle CJS modules for ESM consumption if absolutely necessary.","cause":"You are attempting to use `require('harp')` within an ES Module (ESM) context, which does not support CommonJS `require` calls.","error":"ReferenceError: require is not defined"},{"fix":"Upgrade Harp to `v0.20.3` or a later version. If the issue persists on newer versions, simplify complex template structures or report the issue to the Harp repository.","cause":"This can occur during the `harp compile` process, especially in `v0.20.2`, due to an internal bug with certain project structures or large compilation tasks.","error":"RangeError: Maximum call stack size exceeded"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"harp","cli_version":null}