-
Notifications
You must be signed in to change notification settings - Fork 0
Troubleshooting
Ordered by how often they come up.
Expected. pnpm 10 and later require install scripts to be approved and only honour the list in pnpm-workspace.yaml. npx shirones init writes that file before installing, so the normal flow never hits this.
If you installed the package first, run npx shirones init (which repairs the approval file) and then pnpm install.
Same cause. With unapproved build scripts pending, pnpm exec and pnpm <cli> refuse to run. Use npx shirones init, or ./node_modules/.bin/shirones init.
Recent pnpm releases can enforce a non-zero minimumReleaseAge. Check whether that policy is deliberate for your project and wait it out if so. For a one-off local test, --config.minimumReleaseAge=0 — but do not commit that override to a real project.
astro.config.mjs existed before you ran init, so it was left alone and never wired the theme in. Run npx shirones init --force, which backs the existing config up to .shirones-backup/ and writes the template. Check the backup afterwards — if you had other integrations configured, you will want to merge them back.
That is what the flag does. Everything that was replaced is in .shirones-backup/ as a complete tree. Use plain init to report drift, or init --update to add missing files without replacing anything.
Tailwind v4's automatic content detection does not scan node_modules. As a package, the theme's components are inside node_modules, so the base utilities — w-full, mx-auto, inline-flex, min-h-screen — are never generated, while the theme's own CSS variables and Stylus component styles survive. The result is a site that is styled but structurally collapsed.
The fix lives in the theme's src/styles/main.css, immediately after @import "tailwindcss":
@source "../**/*.{astro,svelte,ts,tsx,js,jsx,mjs,cjs,md,mdx,html}";The path is relative to the CSS file, so it points at the theme's own src/ in both modes. This is shipped correctly; if it regresses after an upstream theme change, that is the line to look for.
Collect class="…" from the rendered HTML as the used set. Concatenate every stylesheet plus inline <style> blocks, strip Tailwind's backslash escapes, and extract the defined selectors. Then compare what the package build is missing against what a source-mode build is missing — only the difference is meaningful. Both builds legitimately "miss" on the order of 150 selectors that are escaped or generated at runtime.
Skipping the unescaping step produces hundreds of false positives and will send you chasing classes that are fine.
A collection's base does not match where your content is. In a package-mode project content lives under shirones/content/, so the bases read ./shirones/content/posts and so on — not ./src/content/posts, which is the theme repository's own layout.
This is a warning, not an error. Astro logs it and builds the site with that collection silently empty, which is why it is easy to ship. Check src/content.config.ts after moving content, and after init --force.
Something assumed process.cwd() was the theme root. In package mode cwd is your project. This is a theme bug rather than a configuration problem — if you hit it, report the stack.
The theme re-creates the CommonJS globals for inlined dependencies. If you see this, the shim has stopped applying, almost certainly because of a Vite or Astro major upgrade. Report it with your Astro version; there is no user-side workaround.
sharp is memory-hungry and processes images in parallel. On a small CI runner this shows up as the process disappearing with no error message — a SIGKILL from the OOM killer, usually somewhere in the middle of the /_astro/*.webp list.
Give the runner more memory, or add swap. Reducing Node's heap ceiling (NODE_OPTIONS=--max-old-space-size=1200) helps more than you would expect, because it leaves room for sharp's native allocations instead of letting V8 take everything.
The image endpoint's route and the trailing-slash policy have to agree, and the transform that appends the slash runs during config resolution — before the integration's hook. The integration sets both explicitly.
If you set trailingSlash yourself in astro.config.mjs, the integration's value still wins, so this should not happen. If it does, something else is reconfiguring the image endpoint; check for another integration doing the same.
Config files are watched and the loader's cache is invalidated on change, but the dev server occasionally needs a nudge. Restart it. If the change still does not apply, check that the file you edited is the one being read — npx shirones info prints the resolved config directory.
With fontConfig.subsetting.allowRemoteText: true, the Meting playlist is fetched on every run because the remote text is part of the font cache key. Offline, that is an eight-second timeout per build. Turn allowRemoteText off in development, or accept the delay. See Fonts.
Check the path against the package's. The match is exact after stripping the extension:
ls node_modules/shirones/src/components/atoms/blog/
ls src/components/atoms/blog/A typo produces a valid component that nothing imports, and nothing warns you — there is no way to tell it apart from a component you wrote yourself.
npx shirones info shows the override count per directory. If components:0 when you expected one, the path is wrong.
The integration warns about these at startup. A file in shirones/config/ that matches no module the theme loads is inert — usually because the theme renamed the module. See Updating.
npx shirones info output plus your Astro version covers most reports. For build failures, the full log matters — the theme's integration logs what it detected at startup:
[shirones] installed package mode | content: /you/my-blog/shirones/content
[shirones] [overrides] 42 registered (config:33, data:9, components:0, layouts:0)
[shirones] injected 28 routes
Those three lines narrow down most problems immediately.