feat: add styles.entries config for injecting global stylesheets

.changeset/rare-lemons-whisper.md

@@ -0,0 +1,5 @@
+---
+'@blinkk/root': patch
+---
+
+feat: add `styles.entries` config for injecting global stylesheets (#929)

packages/root/src/core/config.ts

@@ -33,6 +33,25 @@ export interface RootUserConfig {
     exclude?: RegExp[];
   };
 
+  /**
+   * Config for manually injecting stylesheet entries as
+   * `<link rel="stylesheet">` tags.
+   */
+  styles?: {
+    /**
+     * Project-root-relative stylesheet files to include on every rendered
+     * page, e.g. `styles/index.css`.
+     *
+     * Entries are normalized as URL paths, so both `styles/index.css` and
+     * `/styles/index.css` resolve to `/styles/index.css`.
+     *
+     * Manual entries are injected first, then auto-collected CSS
+     * dependencies are merged after. Duplicate URLs are de-duped so each
+     * stylesheet is only injected once.
+     */
+    entries?: string[];
+  };
+
   /**
    * Config options for localization and internationalization.
    */

packages/root/src/render/render.tsx

@@ -227,6 +227,12 @@ export class Renderer {
       });
     }
 
+    // Merge user-configured stylesheet entries first. This allows global
+    // entries to appear before auto-collected stylesheets.
+    this.getConfiguredStyleEntries().forEach((styleEntry) => {
+      cssDeps.add(styleEntry);
+    });
+
     // Parse the HTML for custom elements that are found within the project
     // and automatically inject the script deps for them.
     await this.collectElementDeps(mainHtml, jsDeps, cssDeps);
@@ -580,6 +586,16 @@ export class Renderer {
     return orderedSitemap;
   }
 
+
+  private getConfiguredStyleEntries() {
+    const styleEntries = this.rootConfig.styles?.entries || [];
+    const basePath = this.rootConfig.base || '/';
+    return styleEntries
+      .map((entry) => entry.trim())
+      .filter((entry) => entry)
+      .map((entry) => normalizeStyleEntry(entry, basePath));
+  }
+
   private async renderHtml(html: string, options?: RenderHtmlOptions) {
     const htmlAttrs = options?.htmlAttrs || {};
     const headAttrs = options?.headAttrs || {};
@@ -860,6 +876,11 @@ function sortLocales(a: string, b: string) {
   return a.localeCompare(b);
 }
 
+function normalizeStyleEntry(entry: string, basePath: string) {
+  const normalizedEntry = normalizeUrlPath(entry.replace(/^\.\//, ''));
+  return normalizeUrlPath(`${basePath}/${normalizedEntry}`);
+}
+
 function guessContentType(ext: string): string {
   const normalized = ext.trim().toLowerCase().replace(/^\./, '');
   return CONTENT_TYPES[normalized] || 'application/octet-stream';