@plutocms/core 0.43.0 → 0.44.0

package/CHANGELOG.md

@@ -1,6 +1,13 @@
 # Changelog
 
 
+## [0.44.0](https://github.com/plutocms/pluto/compare/v0.43.0...v0.44.0) (2026-11-01)
+
+
+### Features
+
+* import the Pluto CSS by name: @plutocms/css and @plutocms/css/site ([#336](https://github.com/plutocms/pluto/issues/336)) ([4d4b404](https://github.com/plutocms/pluto/commit/4d4b404070f186167e020bdcadf4e4df5d0948ef))
+
 ## [0.43.0](https://github.com/plutocms/pluto/compare/v0.42.0...v0.43.0) (2026-11-01)
 
 

package/FEATURES.md

@@ -51,7 +51,7 @@ policies shared by every project here.
 - Pluto UI tokens: the official palette (tholin, haze, heart, kuiper) and fonts (Public Sans,
   Fredoka) in `@theme`, for every app. The admin theme is generated from them.
   @.claude/skills/admin-theme/SKILL.md
-- Pluto site theme: the opt-in `#build/pluto-site.css` gives a public site the look of the Pluto
+- Pluto site theme: the opt-in `@import '@plutocms/css/site'` gives a public site the look of the Pluto
   docs (the fonts, the shades of the app colors, a deep-space dark mode, `pluto-sky`,
   `pluto-site-header`). The official templates use it.
   @.claude/skills/single-tailwind-build/SKILL.md
@@ -67,7 +67,7 @@ policies shared by every project here.
 - Settings pages: `/admin/settings` is a section with tabs. A layer adds a tab with a `settingsPages` entry and a page file at `pages/admin/settings/<x>.vue`. The tabs show with 2 or more pages, the sidebar and the command palette list them, and a tab can need a capability (`'*'` is admin only). The capability picker groups by layer. @.claude/skills/extension-registry/SKILL.md
 - Mail: a mail driver contract (`sendPlutoMail`, `registerMailDriver`) with Resend, dev (console and Mailpit) and none drivers, plain-TypeScript email templates (test, invite) translated by a server translator, and a guided `Settings > Email` page (admin only) that checks the key, adds and verifies a domain, and tests the setup. Secrets stay in the environment. @.claude/skills/mail/SKILL.md
 - Single Tailwind build: the app owns the only Tailwind build. The pluto-css module generates
-  `#build/pluto.css` from each layer's `pluto-layer.css`, adds a fallback entry, and warns
+  `#build/pluto.css` from each layer's `pluto-layer.css` (the app imports it as `@plutocms/css`), adds a fallback entry, and warns
   about a wrong CSS setup. @.claude/skills/single-tailwind-build/SKILL.md
 - Git CMS: a standalone CMS with Markdown posts in a Git repo. Out of the box it publishes to the
   local Git repo (dev only: each save is a local commit, `commit.local`); a GitHub App publishes

package/app/assets/css/pluto-layer.css

@@ -5,9 +5,9 @@
  *
  *   @import 'tailwindcss';
  *   @import '@nuxt/ui';
- *   @import '#build/pluto.css';
+ *   @import '@plutocms/css';
  *
- * `#build/pluto.css` imports this file (and the same file of every other
+ * `@plutocms/css` (core generates it) imports this file (and the same file of every other
  * Pluto layer). Rules for this file:
  * - Do not import tailwindcss or @nuxt/ui here.
  * - Use only @theme, @custom-variant, @utility, unlayered rules, and

package/app/assets/css/pluto-site-theme.css

@@ -4,8 +4,8 @@
  *
  *   @import 'tailwindcss';
  *   @import '@nuxt/ui';
- *   @import '#build/pluto.css';
- *   @import '#build/pluto-site.css';
+ *   @import '@plutocms/css';
+ *   @import '@plutocms/css/site';
  *
  * It does not choose the colors. Set them in app.config.ts, for example
  * `ui.colors: { primary: 'tholin', secondary: 'haze', neutral: 'kuiper' }`. The rules below use

package/modules/pluto-css/css-entries.ts

@@ -5,6 +5,12 @@ import { dirname, isAbsolute, join, relative, resolve } from 'node:path'
 /** A layer's own CSS file, by convention. See the single-tailwind-build skill. */
 export const LAYER_CSS_FILE = 'assets/css/pluto-layer.css'
 
+/** The name that an app's CSS entry imports: an alias of `#build/pluto.css`. */
+export const PLUTO_CSS_IMPORT = '@plutocms/css'
+
+/** The opt-in Pluto site theme: an alias of `#build/pluto-site.css`. */
+export const PLUTO_SITE_CSS_IMPORT = '@plutocms/css/site'
+
 function toPosix(path: string): string {
   return path.replaceAll('\\', '/')
 }
@@ -41,7 +47,8 @@ export function renderPlutoCss(files: string[], buildDir: string): string {
 
 /**
  * Renders `#build/pluto-site.css`: the opt-in Pluto site theme of core
- * (app/assets/css/pluto-site-theme.css). An app imports it after `#build/pluto.css`.
+ * (app/assets/css/pluto-site-theme.css). An app imports it (`@plutocms/css/site`)
+ * after `@plutocms/css`.
  */
 export function renderPlutoSiteCss(file: string, buildDir: string): string {
   return [
@@ -70,7 +77,7 @@ export function renderPlutoEntryCss(): string {
     '/* Fallback Tailwind entry: the app has no CSS entry that imports Tailwind. */',
     '@import "tailwindcss";',
     '@import "@nuxt/ui";',
-    '@import "#build/pluto.css";',
+    `@import "${PLUTO_CSS_IMPORT}";`,
     '',
   ].join('\n')
 }
@@ -106,7 +113,7 @@ export interface CssEntryInfo {
   tailwind: boolean
   /** It imports `@nuxt/ui`. */
   nuxtUi: boolean
-  /** It imports `#build/pluto.css`. */
+  /** It imports `@plutocms/css` (or the generated `#build/pluto.css` itself). */
   plutoCss: boolean
 }
 
@@ -145,8 +152,8 @@ export function analyzeCssEntry(
       } else if (specifier === '@nuxt/ui') {
         info.nuxtUi = true
       } else if (
-        /(?:^|\/)pluto\.css$/.test(specifier) &&
-        specifier.includes('#build')
+        specifier === PLUTO_CSS_IMPORT ||
+        (/(?:^|\/)pluto\.css$/.test(specifier) && specifier.includes('#build'))
       ) {
         info.plutoCss = true
       } else {
@@ -188,8 +195,7 @@ export function checkCssSetup(
 ): CssSetupReport {
   const warnings: string[] = []
   const tailwindEntries = entries.filter((entry) => entry.tailwind)
-  const snippet =
-    "  @import 'tailwindcss';\n  @import '@nuxt/ui';\n  @import '#build/pluto.css';"
+  const snippet = `  @import 'tailwindcss';\n  @import '@nuxt/ui';\n  @import '${PLUTO_CSS_IMPORT}';`
 
   if (tailwindEntries.length === 0) {
     return { injectFallback: true, warnings }
@@ -214,7 +220,7 @@ export function checkCssSetup(
 
   if (!tailwindEntries.some((entry) => entry.plutoCss)) {
     warnings.push(
-      `No CSS entry imports #build/pluto.css. The admin theme and layer tokens are missing. Start the app's CSS entry with:\n${snippet}`
+      `No CSS entry imports ${PLUTO_CSS_IMPORT}. The admin theme and layer tokens are missing. Start the app's CSS entry with:\n${snippet}`
     )
   }
 

package/modules/pluto-css/index.ts

@@ -1,4 +1,5 @@
 import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import {
   addTemplate,
@@ -11,6 +12,8 @@ import {
   analyzeCssEntry,
   checkCssSetup,
   findLayerCssFiles,
+  PLUTO_CSS_IMPORT,
+  PLUTO_SITE_CSS_IMPORT,
   renderPlutoCss,
   renderPlutoEntryCss,
   renderPlutoSiteCss,
@@ -27,13 +30,17 @@ export interface PlutoCssOptions {
  *
  *   @import 'tailwindcss';
  *   @import '@nuxt/ui';
- *   @import '#build/pluto.css';
+ *   @import '@plutocms/css';
  *
- * - `#build/pluto-site.css` (opt-in) imports the Pluto site theme of core
- *   (app/assets/css/pluto-site-theme.css): the look of the Pluto docs for a site.
- * - `#build/pluto.css` imports each layer's app/assets/css/pluto-layer.css
- *   (tokens, the admin theme). Nuxt UI already adds `@source` for every
- *   layer's app/ dir, so this file adds no sources.
+ * - `@plutocms/css` is an alias of the generated `#build/pluto.css`. It imports
+ *   each layer's app/assets/css/pluto-layer.css (tokens, the admin theme), so one
+ *   import covers every layer of the app. Nuxt UI already adds `@source` for
+ *   every layer's app/ dir, so this file adds no sources.
+ * - `@plutocms/css/site` (opt-in) is an alias of `#build/pluto-site.css`: the
+ *   Pluto site theme of core (app/assets/css/pluto-site-theme.css), the look of
+ *   the Pluto docs for a site.
+ * - The names are aliases, not npm packages, so they resolve with every package
+ *   manager, also when the app installs only an outer layer.
  * - An app with no Tailwind entry (a layer repo run on its own, or an app
  *   with no CSS) gets the fallback entry `#build/pluto-entry.css`.
  * - The module warns about a layer that registers its own Tailwind build,
@@ -59,7 +66,7 @@ export default defineNuxtModule<PlutoCssOptions>({
     })
 
     // The opt-in site theme of core. An app that wants the look of the Pluto
-    // docs imports `#build/pluto-site.css` after `#build/pluto.css`.
+    // docs imports `@plutocms/css/site` after `@plutocms/css`.
     const siteTheme = fileURLToPath(
       new URL('../../app/assets/css/pluto-site-theme.css', import.meta.url)
     )
@@ -69,6 +76,18 @@ export default defineNuxtModule<PlutoCssOptions>({
       getContents: () => renderPlutoSiteCss(siteTheme, nuxt.options.buildDir),
     })
 
+    // The names that an app's CSS entry imports. Tailwind resolves `@import`
+    // through the Vite aliases. `/site` comes first: an alias also matches the
+    // paths under its name, so `@plutocms/css` would take `@plutocms/css/site`.
+    nuxt.options.alias[PLUTO_SITE_CSS_IMPORT] = join(
+      nuxt.options.buildDir,
+      'pluto-site.css'
+    )
+    nuxt.options.alias[PLUTO_CSS_IMPORT] = join(
+      nuxt.options.buildDir,
+      'pluto.css'
+    )
+
     addTemplate({
       filename: 'pluto-entry.css',
       write: true,

package/nuxt.config.ts

@@ -43,7 +43,7 @@ export default defineNuxtConfig({
 
   // No `css` entry: the app's CSS entry owns the one Tailwind build, and
   // modules/pluto-css adds this layer's pluto-layer.css to it through
-  // #build/pluto.css. See the single-tailwind-build skill.
+  // @plutocms/css (#build/pluto.css). See the single-tailwind-build skill.
 
   runtimeConfig: {
     // Private mail settings. Empty defaults on purpose: Nuxt reads

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@plutocms/core",
   "type": "module",
-  "version": "0.43.0",
+  "version": "0.44.0",
   "description": "The base layer every Pluto app extends: the admin, the content model, and the Git CMS",
   "author": "Victor Ribeiro",
   "license": "MIT",