How to Properly Load CSS and JS Files in HonoX SSG Builds

HonoX is a lightweight web framework based on Hono, designed to run in serverless environments like Cloudflare Workers. This article explains how to configure CSS and JS files to load correctly in Static Site Generation (SSG) builds for HonoX projects.

The Problem

When performing SSG builds with HonoX, you might encounter the following issues with default settings:

1. CSS files not loading correctly
2. Client-side JavaScript not functioning
3. Islands components not hydrating properly

To resolve these issues, proper configuration of vite.config.ts is essential.

Solution: Configuring vite.config.ts

Here's an example configuration for properly loading CSS and JS in HonoX SSG builds:

import tailwindcss from "@tailwindcss/vite";
import honox from "honox/vite";
import { defineConfig } from "vite";
import ssg from "@hono/vite-ssg";
import client from "honox/vite/client";

// Specify the entry point
const entry = "./app/server.ts";

export default defineConfig(({ mode }) => {
  // Client mode configuration
  if (mode === "client") {
    return {
      plugins: [
        client({
          input: ["./app/style.css"], // CSS file to load on client side
        }),
        tailwindcss(),
      ],
    };
  }

  // Server and SSG mode configuration
  return {
    build: {
      emptyOutDir: false, // Don't empty the dist directory during build
    },
    plugins: [
      honox({
        client: {
          input: ["./app/style.css"], // Same CSS file to load on server side
        },
      }),
      tailwindcss(),
      ssg({ entry }), // SSG configuration
    ],
  };
});

Key Points

1. Specify the Same CSS File for Both Client and Server

// Client mode
client({
  input: ["./app/style.css"],
}),

// Server/SSG mode
honox({
  client: {
    input: ["./app/style.css"],
  },
}),

By specifying the same CSS file paths in both places, styles are applied on both client-side and server-side.

2. SSG Plugin Configuration

import ssg from "@hono/vite-ssg";

// ...

ssg({ entry }),

Use the @hono/vite-ssg plugin and specify the entry point (typically app/server.ts). This plugin handles the SSG build process.

3. emptyOutDir Option

build: {
  emptyOutDir: false,
},

Setting emptyOutDir: false ensures that the dist directory is not completely emptied during the build, preserving client build artifacts.

Important Notes

• Adjust the app/style.css path to match your project's CSS file location.
• To load multiple CSS files, add them to the input array: input: ["./app/style.css", "./app/other-style.css"]
• JavaScript files can be added to the input array in the same way.

Working with Islands Architecture

If you're using HonoX's Islands architecture, pay attention to these points to ensure client-side hydration works properly:

1. Place Islands components in the app/islands/ directory
2. Ensure the client-side entry point (typically app/client.ts) is correctly configured

Conclusion

To properly load CSS and JS files in HonoX SSG builds, it's crucial to configure vite.config.ts appropriately for both client and server modes. Use the configurations presented in this article as a reference and adjust them to fit your project's needs.

Especially when using Islands components, pay careful attention to CSS and JavaScript configuration to ensure client-side hydration works correctly. With proper configuration, you can achieve fast, efficient site generation and user experience.