feat(core): add allLayers option to output all layer names (#5057)

zyyv · web-flow · commit b55b4628ce23 · 2026-01-12T15:15:19.000+08:00
diff --git a/docs/config/index.md b/docs/config/index.md
@@ -88,6 +88,18 @@ Specifies the name of the CSS layer the internal layer should be output to (can
 If `undefined` is return, the internal layer name wil be used as the CSS layer name.
 If `null` is return, the internal layer will not be output to a CSS layer.
 
+#### allLayers
+
+- **Type:** `boolean`
+
+Force output all css layers, even if they are not used.
+
+For example:
+
+```css
+@layer theme, preflights, [unused-layer], default;
+```
+
 ### sortLayers
 
 - **Type:** `(layers: string[]) => string[]`
diff --git a/docs/config/layers.md b/docs/config/layers.md
@@ -101,6 +101,26 @@ outputToCssLayers: {
 }
 ```
 
+## Output All CSS Layers
+
+UnoCSS outputs all used CSS layers by default. If you want to force output all defined CSS layers, you can set the `allLayers` option:
+
+<!-- eslint-skip -->
+
+```ts
+outputToCssLayers: {
+  allLayers: true,
+}
+```
+
+It will output all defined CSS layers, even if they are not used.
+
+```css
+@layer theme, preflights, unused-layer, default;
+
+/* generated CSS */
+```
+
 ## Layers using variants
 
 Layers can be created using variants.
diff --git a/packages-engine/core/src/generator.ts b/packages-engine/core/src/generator.ts
@@ -292,10 +292,8 @@ class UnoGeneratorInternal<Theme extends object = object> {
       )
     })()
 
-    const layers = this.config.sortLayers(Array
-      .from(layerSet)
-      .sort((a, b) => ((this.config.layers[a] ?? 0) - (this.config.layers[b] ?? 0)) || a.localeCompare(b)))
-
+    const sortLayers = (layers: string[]) => this.config.sortLayers(layers.sort((a, b) => ((this.config.layers[a] ?? 0) - (this.config.layers[b] ?? 0)) || a.localeCompare(b)))
+    const layers = sortLayers(Array.from(layerSet))
     const layerCache: Record<string, string> = {}
     const outputCssLayers = this.config.outputToCssLayers
     const getLayerAlias = (layer: string) => {
@@ -395,10 +393,17 @@ class UnoGeneratorInternal<Theme extends object = object> {
 
     const getLayers = (includes = layers, excludes?: string[]) => {
       const layers = includes.filter(i => !excludes?.includes(i))
-      return [
-        outputCssLayers && layers.length > 0 ? `@layer ${layers.map(getLayerAlias).filter(notNull).join(', ')};` : undefined,
-        ...layers.map(i => getLayer(i) || ''),
-      ].filter(Boolean).join(nl)
+      const css = layers.map(getLayer).filter(Boolean)
+
+      if (outputCssLayers) {
+        let layerNames = layers
+        if (typeof outputCssLayers === 'object' && outputCssLayers.allLayers) {
+          layerNames = sortLayers(Object.keys(this.config.layers))
+        }
+        if (layerNames.length > 0)
+          css.unshift(`@layer ${layerNames.map(getLayerAlias).filter(notNull).join(', ')};`)
+      }
+      return css.join(nl)
     }
 
     const setLayer = async (layer: string, callback: (content: string) => Promise<string>) => {
diff --git a/packages-engine/core/src/types.ts b/packages-engine/core/src/types.ts
@@ -560,6 +560,13 @@ export interface OutputCssLayersOptions {
    * Return `null` to specify that the layer should not be output to any css layer.
    */
   cssLayerName?: (internalLayer: string) => string | undefined | null
+
+  /**
+   * Force output all css layers, even if they are not used.
+   *
+   * @example `@layer theme, preflights, [unused-layer], default;`
+   */
+  allLayers?: boolean
 }
 
 export type AutoCompleteTemplate = string
diff --git a/packages-engine/core/test/__snapshots__/use-css-layer.test.ts.snap b/packages-engine/core/test/__snapshots__/use-css-layer.test.ts.snap
@@ -14,6 +14,26 @@ exports[`use-css-layer > change layer name 1`] = `
 }"
 `;
 
+exports[`use-css-layer > output all layers 1`] = `
+"@layer a, imports, preflights, shortcuts, default, custom;
+/* layer: a */
+@layer a{
+.a{name:foo;}
+}
+/* layer: preflights */
+@layer preflights{
+body { background: red; }
+}
+/* layer: default */
+@layer default{
+.c{name:baz;}
+}
+/* layer: custom */
+@layer custom{
+.b{name:bar;}
+}"
+`;
+
 exports[`use-css-layer > static 1`] = `
 "@layer shortcuts, a, b, c, d, default, s;
 /* layer: shortcuts */
diff --git a/packages-engine/core/test/use-css-layer.test.ts b/packages-engine/core/test/use-css-layer.test.ts
@@ -41,4 +41,28 @@ describe('use-css-layer', () => {
     const { css } = await uno.generate('w-1 h-1 custom-shortcut', { preflights: false })
     expect(css).toMatchSnapshot()
   })
+
+  it('output all layers', async () => {
+    const uno = await createGenerator({
+      rules: [
+        ['a', { name: 'foo' }, { layer: 'a' }],
+        ['b', { name: 'bar' }, { layer: 'custom' }],
+        ['c', { name: 'baz' }],
+      ],
+      layers: {
+        a: -300,
+        custom: 100,
+      },
+      outputToCssLayers: {
+        allLayers: true,
+      },
+      preflights: [
+        {
+          getCSS: () => `body { background: red; }`,
+        },
+      ],
+    })
+    const { css } = await uno.generate('a b c')
+    expect(css).toMatchSnapshot()
+  })
 })
