Skip to content

GettingStarted

Jump to bottom
yCENzh edited this page Sep 19, 2026 · 1 revision

Getting started

Requirements

  • Node 22.12 or newer. The generated package.json pins engines.node to >=22.12.0, and npx shirones info will tell you if you are below it.
  • pnpm. init writes a pnpm project. It records the pnpm version that was current when the package was published and sets packageManager accordingly. If you use npm or yarn, let init finish and then migrate the project yourself — init does not configure other package managers, and a couple of behaviours described below are pnpm-specific.

Install

mkdir my-blog
cd my-blog
npx shirones init
pnpm dev

init does five things, in this order:

  1. Writes package.json with astro, shirones and the theme's peer dependencies.
  2. Writes pnpm-workspace.yaml with the install-script approvals (see below).
  3. Scaffolds shirones/config/, shirones/content/, public/, src/content.config.ts, astro.config.mjs and tsconfig.json.
  4. Runs the install.
  5. Prints what it created and what it skipped.

Then pnpm dev and you have a running site with the example content.

Why init writes pnpm-workspace.yaml

pnpm 10 and later refuse to run a dependency's install script until you approve it. The theme needs two:

  • sharp — Astro's image service loads it from your project root
  • esbuild — used to bundle your TypeScript config at config time

init writes both approvals before installing, so the normal flow never trips over this. You will only see ERR_PNPM_IGNORED_BUILDS if you ran pnpm add shirones yourself before running init. The fix is to run npx shirones init (which repairs the approval file) and then pnpm install.

Your first post

Content lives under shirones/content/. The scaffold ships a handful of example posts; replace them.

shirones/content/posts/hello-world.md
---
title: Hello world
published: 2026-01-15
description: A first post.
tags: [meta]
category: notes
---

Body goes here. Markdown, MDX, whatever the file extension says.

published is the only required field besides title. Everything else has a default — the full list is in Content.

Moments (the short-form feed) go in shirones/content/moments/, and free-form pages like an About page go in shirones/content/spec/.

Dev and build

pnpm dev      # dev server
pnpm build    # static output in dist/
pnpm preview  # serve the built output

These are plain Astro scripts. The theme does not wrap them.

Two things happen at config time that are worth knowing about because they show up in the log:

[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

The first line says which mode the integration detected. The second counts files in your project that replace a theme file — zero for components and layouts until you add some. The third is the theme's page files being registered with Astro; you do not have a src/pages/ directory, so this is where your routes come from.

Fonts on the first build

The first pnpm build subsets the configured fonts against the characters your content actually uses. That takes a few seconds and writes .woff2 files into .shirones/fonts/. Subsequent builds reuse the cache unless your content changed.

pnpm dev does not subset — it serves the full font files so the dev server starts fast. This trips people up occasionally; the details are in Fonts.

If you would rather start from the theme repository

Everything above is the package workflow. There is a second one: clone the theme repository and build it directly. You get the same site, but the theme's source is in your tree instead of in node_modules, which is what you want if you are changing the theme itself rather than a blog.

The integration detects which situation it is in and adjusts — config paths, route injection, font output location. You do not configure this. The mechanics are in How it works.

Next

Clone this wiki locally