Orientation Arc
Routing Algorithms
Rendering and JSX
Runtime Adapters
Middleware Ecosystem
Developer Helpers
System Utilities
The following files were used as context for generating this wiki page:
Hono provides a robust, experimental CSS-in-JS solution designed to work seamlessly in both server-side rendering (SSR) and client-side DOM environments. This subsystem addresses the challenge of managing scoped styles in a modular application by generating hash-based class names at runtime, minimizing style collisions, and supporting efficient style injection.
At its core, the CSS styling mechanism treats CSS rules as structured data. By utilizing template literals, it allows developers to define styles naturally, while the underlying helper functions transform these templates into minified style strings and associated class name objects. These objects encapsulate selectors, class identifiers, and the actual style string, which are then used by the rendering engine to either inject standard <style> tags during SSR or dynamically update the document’s stylesheet via CSSStyleSheet in the DOM.
The system is highly integrated with Hono’s JSX ecosystem. When used in a server environment, the styling helper manages style injection through callback mechanisms that hook into the HTML string rendering flow. In the browser, the DOM-specific CSS module provides an efficient bridge to the browser’s native CSS Object Model (CSSOM). This dual-mode approach ensures that whether the site is served via static generation or dynamic requests, styles are handled in a performant, scoped-by-default, and standard-compliant manner.
The subsystem includes a robust minification engine that operates directly on the raw CSS template string. It uses a series of regular expressions to strip unnecessary whitespace, comments, and redundant semicolons, effectively reducing the payload size before the styles are rendered into the final output.
The minify function utilizes a complex regex minifyCssRe that matches string literals as a protected group to ensure that content inside quotes is not unintentionally modified during the stripping process.
// Example of the minification mechanism logic
export const minify = (css: string): string => {
return css.replace(minifyCssRe, (_, $1, $2, $3, $4) => $1 || $2 || $3 || $4 || '')
}Sources: src/helper/css/common.ts:100-102
The createCssContext function is the factory that configures the styling environment. It manages state between renders via a WeakMap, allowing the engine to track which class names have already been injected into the current request context.
During SSR, if a style has not been rendered yet, a callback is registered. When the stream is finalized, this callback resolves the missing styles and injects them into the document, ensuring that only necessary styles are shipped.
Sources: src/helper/css/index.ts:71-122
In the DOM environment, the CSS styling mechanism bypasses standard string injection in favor of direct manipulation of CSSStyleSheet. The createCssJsxDomObjects function manages a singleton stylesheet entry for the application.
findStyleSheet attempts to locate the <style> tag by ID.Set to the object to track addedStyles locally, preventing duplicate rule insertions.insertRule function uses sheet.insertRule to push new definitions to the browser engine, which is significantly faster than DOM tree manipulation for high-frequency style updates.Note
The styling subsystem uses a specific internal identifier, DEFAULT_STYLE_ID ('hono-css'), to locate or create the <style> tag used for injection.
Sources: src/jsx/dom/css.ts:77-113
The following example demonstrates how to define scoped styles using the CSS helper and apply them to JSX components.
import { css, cx } from 'hono/css'
const buttonClass = css`
/* Custom label */
background-color: blue;
color: white;
padding: 10px;
`
export const App = () => (
<button className={cx(buttonClass, 'my-other-class')}>
Click Me
</button>
)Sources: src/helper/css/index.ts:224-231