Hugo and TypeScript: A Comprehensive Guide

Hugo is a popular open-source static site generator written in Go. It is known for its speed and flexibility, allowing developers to build websites quickly. On the other hand, TypeScript is a typed superset of JavaScript that compiles to plain JavaScript. Combining Hugo with TypeScript can bring the benefits of static typing and modern JavaScript features to your Hugo projects. This blog will explore the fundamental concepts, usage methods, common practices, and best practices when using TypeScript in a Hugo project.

Table of Contents#

  1. Fundamental Concepts
  2. Usage Methods
  3. Common Practices
  4. Best Practices
  5. Conclusion
  6. References

Fundamental Concepts#

Hugo#

Hugo is a static site generator that takes content written in Markdown or other formats, applies templates, and generates a complete static website. It has a simple directory structure, where content files are stored in the content directory, templates in the layouts directory, and static assets in the static directory.

TypeScript#

TypeScript adds static typing to JavaScript. This means that you can define the types of variables, function parameters, and return values. Static typing helps catch errors early in the development process and makes the code more maintainable. For example:

// A simple TypeScript function with typed parameters and return value
function add(a: number, b: number): number {
    return a + b;
}
 
const result = add(1, 2);

Combining Hugo and TypeScript#

When using TypeScript in a Hugo project, you typically write your TypeScript code, compile it to JavaScript, and then include the compiled JavaScript in your Hugo templates. This allows you to take advantage of TypeScript's features while still leveraging Hugo's static site generation capabilities.

Usage Methods#

Setting up a Hugo Project#

First, make sure you have Hugo installed on your system. Then, create a new Hugo project:

hugo new site my-hugo-site
cd my-hugo-site

Installing TypeScript#

You need to install TypeScript as a development dependency. Navigate to your Hugo project directory and run the following command:

npm init -y
npm install typescript --save-dev

Configuring TypeScript#

Create a tsconfig.json file in the root of your Hugo project to configure TypeScript. Here is a basic example:

{
    "compilerOptions": {
        "target": "ES6",
        "module": "ES6",
        "outDir": "./static/js",
        "rootDir": "./src",
        "strict": true,
        "esModuleInterop": true,
        "skipLibCheck": true,
        "forceConsistentCasingInFileNames": true
    },
    "include": ["src/**/*.ts"]
}

Writing TypeScript Code#

Create a src directory in your Hugo project and write your TypeScript code inside it. For example, create a file named main.ts:

// src/main.ts
function greet(name: string) {
    return `Hello, ${name}!`;
}
 
const message = greet('World');
console.log(message);

Compiling TypeScript#

To compile your TypeScript code, add a script to your package.json file:

{
    "scripts": {
        "build:ts": "tsc"
    }
}

Then, run the following command to compile your TypeScript code:

npm run build:ts

Including Compiled JavaScript in Hugo Templates#

In your Hugo templates (e.g., layouts/index.html), you can include the compiled JavaScript file:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>{{ .Site.Title }}</title>
</head>
<body>
    <h1>{{ .Site.Title }}</h1>
    <script src="/js/main.js"></script>
</body>
</html>

Common Practices#

Organizing TypeScript Code#

Group your TypeScript code into modules based on functionality. For example, you can have separate modules for handling forms, making API calls, or managing UI interactions.

// src/api.ts
export async function fetchData() {
    const response = await fetch('https://api.example.com/data');
    const data = await response.json();
    return data;
}
// src/main.ts
import { fetchData } from './api';
 
async function main() {
    const data = await fetchData();
    console.log(data);
}
 
main();

Handling Static Assets#

If your TypeScript code depends on static assets like images or CSS files, make sure to reference them correctly. You can use Hugo's built-in functions to handle asset paths.

// src/ui.ts
const imagePath = '/images/logo.png';
const img = document.createElement('img');
img.src = imagePath;
document.body.appendChild(img);

Best Practices#

Minimizing Bundle Size#

Use techniques like code splitting and tree shaking to reduce the size of your compiled JavaScript bundle. You can use tools like Webpack or Rollup in combination with TypeScript to achieve this.

Error Handling#

Implement proper error handling in your TypeScript code. Use try-catch blocks when making asynchronous calls or performing operations that can throw errors.

async function main() {
    try {
        const data = await fetchData();
        console.log(data);
    } catch (error) {
        console.error('Error fetching data:', error);
    }
}

Testing#

Write unit tests for your TypeScript code using testing frameworks like Jest or Mocha. This helps ensure the reliability of your code.

npm install jest @types/jest ts-jest --save-dev

Create a jest.config.js file:

module.exports = {
    preset: 'ts-jest',
    testEnvironment: 'node'
};

Write a test for your greet function:

// src/main.test.ts
import { greet } from './main';
 
test('greet function should return a greeting', () => {
    const result = greet('John');
    expect(result).toBe('Hello, John!');
});

Run the tests:

npx jest

Conclusion#

Combining Hugo and TypeScript can enhance the development experience of building static websites. Hugo provides a fast and flexible static site generation platform, while TypeScript brings the benefits of static typing and modern JavaScript features. By following the usage methods, common practices, and best practices outlined in this blog, you can efficiently use TypeScript in your Hugo projects and build high-quality websites.

References#

2025-10