# hugo-extended

> ✏️ Plug-and-play binary wrapper for Hugo Extended, the awesomest static-site generator.

Latest version **0.166.0** (published 2026-09-10) · MIT license · 0 weekly downloads

## Install

```sh
npm install hugo-extended
pnpm add hugo-extended
yarn add hugo-extended
bun add hugo-extended
```

Provides the commands `hugo`, `hugo-extended`.

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.166.0 |
| Published | 2026-09-10 |
| First published | 2020-01-31 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18.17 |
| Dependencies | 2 |
| Unpacked size | 135.5 KB |
| Known vulnerabilities | 0 (+2 in 1 direct dependencies) |
| Install scripts | yes |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 31 |
| Author | Jake Jarvis |
| Maintainers | jakejarvis |
| Keywords | hugo, hugo extended, gohugoio, cli, front-end, bin, binary, wrapper, static site generator, static-site, ssg, static, markdown, blog, frontmatter, go, golang |

## Links

- npm: https://www.npmjs.com/package/hugo-extended
- Repository: https://github.com/jakejarvis/hugo-extended
- Homepage: https://github.com/jakejarvis/hugo-extended#readme
- Issues: https://github.com/jakejarvis/hugo-extended/issues
- npm.io page: https://npm.io/package/hugo-extended

## Dependencies (2)

- [tar](https://npm.io/package/tar.md) ^7.5.15
- [adm-zip](https://npm.io/package/adm-zip.md) ^0.5.17

## Alternatives

- [angular-pipes](https://npm.io/package/angular-pipes.md) — 5.6K weekly downloads
- [@ng-web-apis/midi](https://npm.io/package/@ng-web-apis/midi.md) — 2.6K weekly downloads
- [happn-3](https://npm.io/package/happn-3.md) — 1.6K weekly downloads
- [@opensip-cli/lang-go](https://npm.io/package/@opensip-cli/lang-go.md) — 1.2K weekly downloads
- [mongoose-typescript](https://npm.io/package/mongoose-typescript.md) — 85 weekly downloads

## Recent versions

- 0.166.0 (latest) — 2026-09-10
- 0.165.0 — 2026-09-06
- 0.164.0 — 2026-07-06
- 0.163.3 — 2026-06-21
- 0.163.2 — 2026-06-15
- 0.163.1 — 2026-06-12
- 0.163.0 — 2026-06-09
- 0.162.1 — 2026-05-28
- 0.162.0 — 2026-05-26
- 0.161.1 — 2026-04-29
- 0.161.0 — 2026-04-28
- 0.160.1 — 2026-04-08
- 0.160.0 — 2026-04-05
- 0.159.2 — 2026-04-03
- 0.159.1 — 2026-04-03
- … 258 more at https://npm.io/package/hugo-extended/versions

## README

# <img src="https://raw.githubusercontent.com/gohugoio/gohugoioTheme/master/static/images/hugo-logo-wide.svg?sanitize=true" alt="Hugo" width="115"> via NPM

[![NPM Version](https://img.shields.io/npm/v/hugo-extended?color=blue)](https://www.npmjs.com/package/hugo-extended)
[![NPM Downloads](https://img.shields.io/npm/dw/hugo-extended?color=rebeccapurple)](https://www.npmjs.com/package/hugo-extended)
[![CI status](https://github.com/jakejarvis/hugo-extended/workflows/Run%20tests/badge.svg)](https://github.com/jakejarvis/hugo-extended/actions)

> Plug-and-play binary wrapper for [Hugo Extended](https://gohugo.io/), the awesomest static-site generator. Now with full TypeScript support and type-safe APIs!

## Features

- 🚀 **Zero configuration** — Hugo binary is automatically downloaded on install
- 📦 **Version-locked** — Package version matches Hugo version (e.g., `hugo-extended@0.140.0` = Hugo v0.140.0)
- 🔒 **Type-safe API** — Full TypeScript support with autocomplete for all Hugo commands and flags
- ⚡ **Multiple APIs** — Use CLI, function-based, or builder-style APIs
- 🎯 **Extended by default** — Automatically uses Hugo Extended on supported platforms

## Installation

```sh
npm install hugo-extended --save-dev
# or
yarn add hugo-extended --dev
# or
pnpm add hugo-extended --save-dev
```

### SCSS/PostCSS Support

If you're using Hugo's SCSS features, you'll also want:

```sh
npm install postcss postcss-cli autoprefixer --save-dev
```

These integrate seamlessly with Hugo's [built-in PostCSS pipes](https://gohugo.io/functions/css/postcss/).

## Usage

### CLI Usage

The simplest way — just run `hugo` commands directly:

```jsonc
// package.json
{
  "scripts": {
    "dev": "hugo server --buildDrafts",
    "build": "hugo --minify",
    "build:preview": "hugo --baseURL \"${DEPLOY_PRIME_URL:-/}\" --buildDrafts --buildFuture"
  }
}
```

```sh
npm run dev
```

### Programmatic API

#### Builder-style API

A fluent interface where each Hugo command is a method:

```typescript
import hugo from "hugo-extended";

// Start server
await hugo.server({
  port: 1313,
  buildDrafts: true,
});

// Build site
await hugo.build({
  minify: true,
  environment: "production",
});

// Module commands
await hugo.mod.get();
await hugo.mod.tidy();
await hugo.mod.clean({ all: true });

// Generate shell completions
await hugo.completion.zsh();
```

#### Function-based API

Use `exec()` for commands that output to the console, or `execWithOutput()` to capture the output:

```typescript
import { exec, execWithOutput } from "hugo-extended";

// Start development server with full type safety
await exec("server", {
  port: 1313,
  buildDrafts: true,
  navigateToChanged: true,
});

// Build for production
await exec("build", {
  minify: true,
  cleanDestinationDir: true,
  baseURL: "https://example.com",
});

// Capture command output
const { stdout } = await execWithOutput("version");
console.log(stdout); // "hugo v0.140.0+extended darwin/arm64 ..."

// List all content pages
const { stdout: pages } = await execWithOutput("list all");
```

#### Direct Binary Access

For advanced use cases, get the Hugo binary path directly:

```typescript
import hugo from "hugo-extended";
import { spawn } from "child_process";

const binPath = await hugo();
console.log(binPath); // "/usr/local/bin/hugo" or similar

// Use with spawn, exec, or any process library
spawn(binPath, ["version"], { stdio: "inherit" });
```

### Type Imports

Import Hugo types for use in your own code:

```typescript
import type { HugoCommand, HugoOptionsFor, HugoServerOptions } from "hugo-extended";

// Type-safe option objects
const serverOpts: HugoServerOptions = {
  port: 1313,
  buildDrafts: true,
  disableLiveReload: false,
};

// Generic helper
function runHugo<C extends HugoCommand>(cmd: C, opts: HugoOptionsFor<C>) {
  // ...
}
```

## API Reference

### `exec(command, options?)`

Execute a Hugo command with inherited stdio (output goes to console).

- **command** — Hugo command string (e.g., `"server"`, `"build"`, `"mod clean"`)
- **options** — Type-safe options object (optional)
- **Returns** — `Promise<void>`

### `execWithOutput(command, options?)`

Execute a Hugo command and capture output.

- **command** — Hugo command string
- **options** — Type-safe options object (optional)
- **Returns** — `Promise<{ stdout: string; stderr: string }>`

### `hugo` (default export)

The default export is both callable (returns binary path) and has builder methods:

```typescript
// Get binary path (backward compatible)
const binPath = await hugo();

// Builder methods
await hugo.build({ minify: true });
await hugo.server({ port: 3000 });
```

### Available Commands

All Hugo commands are fully typed with autocomplete:

| Command | Builder Method | Description |
|---------|---------------|-------------|
| `build` | `hugo.build()` | Build your site |
| `server` | `hugo.server()` | Start dev server |
| `new` | `hugo.new()` | Create new content |
| `mod get` | `hugo.mod.get()` | Download modules |
| `mod tidy` | `hugo.mod.tidy()` | Clean go.mod/go.sum |
| `mod clean` | `hugo.mod.clean()` | Clean module cache |
| `mod vendor` | `hugo.mod.vendor()` | Vendor dependencies |
| `list all` | `hugo.list.all()` | List all content |
| `list drafts` | `hugo.list.drafts()` | List draft content |
| `config` | `hugo.config()` | Print configuration |
| `version` | `hugo.version()` | Print version |
| `env` | `hugo.env()` | Print environment |
| ... | ... | [All Hugo commands supported](https://gohugo.io/commands/) |

## Platform Support

Hugo Extended is automatically used on supported platforms:

| Platform | Architecture | Hugo Extended |
|----------|-------------|---------------|
| macOS | x64, ARM64 | ✅ |
| Linux | x64, ARM64 | ✅ |
| Windows | x64 | ✅ |
| Windows | ARM64 | ❌ (vanilla Hugo) |
| FreeBSD | x64 | ❌ (vanilla Hugo) |

## Environment Variables

Customize installation and runtime behavior with these environment variables:

| Variable | Description |
|----------|-------------|
| `HUGO_OVERRIDE_VERSION` | Install a specific Hugo version instead of the package version. Example: `HUGO_OVERRIDE_VERSION=0.139.0 npm install` |
| `HUGO_NO_EXTENDED` | Force vanilla Hugo instead of Extended edition. Example: `HUGO_NO_EXTENDED=1 npm install` |
| `HUGO_SKIP_DOWNLOAD` | Skip the postinstall binary download entirely. Useful for CI caching or Docker layer optimization. |
| `HUGO_BIN_PATH` | Use a pre-existing Hugo binary instead of the bundled one. Example: `HUGO_BIN_PATH=/usr/local/bin/hugo` |
| `HUGO_MIRROR_BASE_URL` | Download from a custom mirror instead of GitHub releases. Example: `HUGO_MIRROR_BASE_URL=https://mirror.example.com/hugo` |
| `HUGO_SKIP_CHECKSUM` | Skip SHA-256 checksum verification. **Use with caution.** |
| `HUGO_QUIET` | Suppress installation progress output. |

### Examples

```sh
# Install a specific older version
HUGO_OVERRIDE_VERSION=0.139.0 npm install hugo-extended

# Skip download for CI caching (when binary is already cached)
HUGO_SKIP_DOWNLOAD=1 npm ci

# Use smaller vanilla Hugo (no SCSS support)
HUGO_NO_EXTENDED=1 npm install hugo-extended

# Use a corporate mirror
HUGO_MIRROR_BASE_URL=https://internal.example.com/hugo npm install hugo-extended
```

## Troubleshooting

### Hugo binary not found

If Hugo seems to disappear (rare edge case), it will be automatically reinstalled on next use. You can also manually trigger reinstallation:

```sh
npm rebuild hugo-extended
```

### macOS installation

As of [v0.153.0](https://github.com/gohugoio/hugo/releases/tag/v0.153.0), Hugo is distributed as a `.pkg` installer for macOS. This package extracts the binary locally using `pkgutil --expand-full`, so **no sudo or global installation is required**. The Hugo binary stays in `node_modules` just like on other platforms.

## License

This project is distributed under the [MIT License](LICENSE). Hugo is distributed under the [Apache License 2.0](https://github.com/gohugoio/hugo/blob/master/LICENSE).

---
_Source: https://npm.io/package/hugo-extended · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._