Necessary Changes

April 15, 2025 6 min read Setup Configuration HBStack Package-Json Project-Setup Metadata

This document outlines the necessary changes to the `package.json` file when starting a new project based on HBStack. It includes details on updating project metadata, repository links, and other essential configurations.

On this page

Modifying the package.json File

The package.json file contains critical metadata about your project, including its name, repository URL, and other identifying information. When starting a new project based on HBStack, you should update this file to reflect your own project’s details.

Current Configuration

The default package.json file for HBStack contains the following configuration:

 1{
 2  "name": "hb-theme",
 3  "description": "The starter theme template of [HB Framework](https://hbstack.dev/).",
 4  "scripts": {},
 5  "repository": {
 6    "type": "git",
 7    "url": "git+https://github.com/hbstack/theme.git"
 8  },
 9  "author": "Razon Yang <razonyang@gmail.com>",
10  "license": "MIT",
11  "bugs": {
12    "url": "https://github.com/hbstack/theme/issues"
13  },
14  "homepage": "https://github.com/hbstack/theme#readme",
15  "devDependencies": {
16    "@fullhuman/postcss-purgecss": "^7.0.0",
17    "autoprefixer": "^10.4.14",
18    "postcss-cli": "^11.0.0",
19    "prettier": "^2.8.8",
20    "prettier-plugin-go-template": "^0.0.13",
21    "prettier-plugin-md-nocjsp": "^1.5.1",
22    "rtlcss": "^4.0.0"
23  },
24  "dependencies": {
25    "@hbstack/node-packages": "^0.1.5"
26  }
27}

Required Changes

For this project, we need to update several fields to reflect the project name hugo-with-docker or whatever is your repo name. Here are the specific changes required:

name: Change from hb-theme to hugo-with-docker
description: Update to describe your specific project
repository.url: Update the GitHub repository URL
bugs.url: Update to reflect your repository’s issues page
homepage: Update to your repository’s homepage URL

Updated Configuration

Here’s how the updated package.json file should look:

 1{
 2  "name": "hugo-with-docker",
 3  "description": "A Hugo project based on HBStack framework with Docker integration",
 4  "version": "0.1.0",
 5  "scripts": {
 6    "dev": "hugo server",
 7    "build": "hugo --minify",
 8    "clean": "rm -rf public resources",
 9    "test": "hugo server --disableFastRender",
10    "debug": "hugo server --debug --verbose --logLevel debug",
11    "debug:build": "hugo --debug --verbose --logLevel debug --minify",
12    "diagnose": "echo '=== Hugo Diagnostics ===' && hugo version && echo '\\n=== Hugo Environment ===' && hugo env && echo '\\n=== Hugo Config ===' && hugo config",
13    "troubleshoot": "echo '=== Project Health Check ===' && npm run diagnose && echo '\\n=== Module Status ===' && npm run check:modules && echo '\\n=== Build Test ===' && npm run check:build",
14    "check:links": "hugo server --navigateToChanged=false --disableFastRender --logLevel info 2>&1 | grep -i 'error\\|warn' || echo 'No link errors found'",
15    "check:config": "hugo config --logLevel info",
16    "check:modules": "hugo mod verify && hugo mod graph",
17    "check:build": "hugo --dry-run --logLevel info",
18    "health": "echo '=== Quick Health Check ===' && hugo version && hugo mod verify && hugo config | head -20"
19  },
20  "repository": {
21    "type": "git",
22    "url": "git+https://github.com/agsayyed/hugo-with-docker.git"
23  },
24  "keywords": ["hugo", "hbstack", "docker", "static-site"],
25  "author": "AG Sayyed <s.ghafoor@outlook.com>",
26  "license": "MIT",
27  "bugs": {
28    "url": "https://github.com/agsayyed/hugo-with-docker/issues"
29  },
30  "homepage": "https://github.com/agsayyed/hugo-with-docker#readme",
31  "devDependencies": {
32    "@fullhuman/postcss-purgecss": "^7.0.0",
33    "autoprefixer": "^10.4.14",
34    "postcss-cli": "^11.0.0",
35    "prettier": "^2.8.8",
36    "prettier-plugin-go-template": "^0.0.13",
37    "prettier-plugin-md-nocjsp": "^1.5.1",
38    "rtlcss": "^4.0.0"
39  },
40  "dependencies": {
41    "@hbstack/node-packages": "^0.1.5"
42  }
43}

Why These Changes Are Important

Updating the package.json file ensures:

Project Identification: Your project will be correctly identified.
Repository Links: Links to your repository, issues, and homepage will be accurate
Attribution: Your authorship is properly recognized
Documentation: The description accurately reflects what your project does

Additional Considerations

You may want to add custom scripts to the scripts section based on your workflow
Consider updating the author field with your information
You can keep the existing dependencies unless you have specific needs

Implementation Steps

Open the package.json file in your project root
Update the fields as shown above, replacing placeholder values with your actual information
Save the file

If you’re using version control, commit these changes:

1git add package.json
2git commit -m "Update package.json with project-specific information"

By making these changes, your project will be properly configured with its own identity while maintaining the benefits of the HBStack framework.

Debug and Troubleshooting Scripts

In addition to the basic project metadata updates, we’ve added comprehensive debugging and troubleshooting scripts to help maintain and diagnose issues with your Hugo project. These scripts provide valuable insights into your project’s health and can help quickly identify common problems.

Added Scripts

The following scripts have been added to the scripts section of package.json:

 1{
 2  "scripts": {
 3    "dev": "hugo server",
 4    "build": "hugo --minify",
 5    "clean": "rm -rf public resources",
 6    "test": "hugo server --disableFastRender",
 7    "debug": "hugo server --debug --verbose --logLevel debug",
 8    "debug:build": "hugo --debug --verbose --logLevel debug --minify",
 9    "diagnose": "echo '=== Hugo Diagnostics ===' && hugo version && echo '\\n=== Hugo Environment ===' && hugo env && echo '\\n=== Hugo Config ===' && hugo config",
10    "troubleshoot": "echo '=== Project Health Check ===' && npm run diagnose && echo '\\n=== Module Status ===' && npm run check:modules && echo '\\n=== Build Test ===' && npm run check:build",
11    "check:links": "hugo server --navigateToChanged=false --disableFastRender --logLevel info 2>&1 | grep -i 'error\\|warn' || echo 'No link errors found'",
12    "check:config": "hugo config --logLevel info",
13    "check:modules": "hugo mod verify && hugo mod graph",
14    "check:build": "hugo --dry-run --logLevel info",
15    "health": "echo '=== Quick Health Check ===' && hugo version && hugo mod verify && hugo config | head -20"
16  }
17}

Script Descriptions

Development Scripts

dev: Standard Hugo development server
build: Production build with minification
clean: Remove generated files and resources
test: Development server without fast render for testing

Debug Scripts

debug: Start Hugo server with full debug output and verbose logging
debug:build: Build with full debug information and verbose logging

Diagnostic Scripts

diagnose: Comprehensive system diagnostics showing Hugo version, environment, and configuration
troubleshoot: Full project health check combining multiple diagnostic checks
health: Quick health check for immediate project status

Validation Scripts

check:links: Check for broken links and navigation issues
check:config: Validate Hugo configuration files
check:modules: Verify and display Hugo module dependencies
check:build: Perform a dry-run build to check for build issues

Usage Examples

Quick Diagnostics

1# Quick project health check
2npm run health
3
4# Full diagnostic information
5npm run diagnose
6
7# Complete troubleshooting session
8npm run troubleshoot

Development Debugging

1# Debug development server issues
2npm run debug
3
4# Debug build problems
5npm run debug:build

Specific Checks

1# Check Hugo modules
2npm run check:modules
3
4# Validate configuration
5npm run check:config
6
7# Test build without generating files
8npm run check:build

Benefits

These scripts provide several advantages:

Quick Problem Identification: Rapidly identify common Hugo issues
Consistent Diagnostics: Standardized approach to troubleshooting across team members
Development Efficiency: Reduce time spent on debugging configuration and build issues
Documentation: Self-documenting diagnostic commands that new team members can easily use
CI/CD Integration: Scripts can be integrated into continuous integration pipelines for automated health checks

When to Use These Scripts

Before starting development: Run npm run health to ensure everything is working
When encountering build issues: Use npm run troubleshoot for comprehensive diagnosis
Module problems: Use npm run check:modules to verify dependencies
Configuration issues: Use npm run check:config to validate settings
Performance problems: Use npm run debug to identify bottlenecks

Project Configuration

Site Configuration

Browse Courses