Innei/Shiro: the Mix Space blog frontend that is now frozen at 10.x

What Shiro actually is, and who it is not for

Shiro is a frontend theme, not a blog engine. It renders content that lives in Mix Space, so it does nothing on its own without a Mix Space Core instance behind it. The README is explicit that Shiro requires Mix Space Core version == 10.x and is not compatible with higher versions. That single line decides most adoption questions before any design consideration comes up.

The audience is narrow and specific: people already inside the Mix Space ecosystem who want a personal site with a timeline, a separate thoughts page, a hero area and activity status, and who would rather configure someone else's frontend than build one. The README lists two example sites, including the author's own. If you are not on Mix Space, this is not a theme you can bolt onto something else.

The maintenance note at the top of the README matters more than the feature list. Shiro has entered maintenance mode: it stays at the current version, no new features are added, and only critical bugs are fixed. The README directs anyone looking for a new personal blog frontend to Yohaku, described there as an independent new project with its own design language, with full code access requiring sponsorship.

The stack behind the paper-and-snow look

The README names the architecture directly: Next.js 16 with the App Router, Jotai for atomic state, Motion for animation, Radix UI for accessible components, Socket.IO for realtime, TailwindCSS v4 and DaisyUI v5 for styling, and TanStack Query for server state. The repository is a pnpm workspace driven by Turborepo, with apps/ and packages/ directories and a root package.json whose scripts route through turbo. The web app is filtered as @shiro/web, which is what the dev script targets and what the Dockerfile builds.

Two mechanisms in the feature list are worth separating from marketing language. The first is realtime notification: the README says visitors receive new post pushes over a WebSocket connection, which is why Socket.IO appears in the stack. The second is activity status, which the README ties to ProcessReporter, a separate project, to show what the site owner is doing in real time. Both depend on services outside this repository.

The Dockerfile shows how tightly the build is bound to deployment configuration. It takes BASE_URL as a build argument and derives NEXT_PUBLIC_API_URL as ${BASE_URL}/api/v2 and NEXT_PUBLIC_GATEWAY_URL as ${BASE_URL}. It also accepts S3_ACCESS_KEY, S3_SECRET_KEY, WEBHOOK_SECRET, TMDB_API_KEY and GH_TOKEN as build arguments, with a comment warning that these must be passed securely and not committed. That is a real constraint: several of these values are baked in at image build time, not read at container start, so rotating them means rebuilding.

Installing Shiro with Docker Compose

The README recommends Docker Compose over the prebuilt release archive. The compose file it ships defines a single service named shiro, using the image innei/shiro:latest, mounting ./.env at /app/apps/web/.env and ./public at /app/apps/web/public, restarting always, and publishing port 2323. The README's quick start mirrors that layout: create a directory, fetch the compose file and the environment template, create a public directory for a custom favicon, then start the stack.

mkdir shiro && cd shiro
wget https://raw.githubusercontent.com/Innei/Shiro/main/docker-compose.yml
wget https://raw.githubusercontent.com/Innei/Shiro/main/.env.template .env

vim .env # 配置环境变量
mkdir public # 放置自定义 Favicon
docker compose up -d

# 后续更新
docker compose pull

The .env file is where the build arguments above have to be supplied, and it is mounted into the container rather than baked into the image, so it is the one file you edit before first start. After docker compose up -d, the site should answer on port 2323; the compose file maps 2323:2323 rather than relying on a proxy. Updates are a pull, not a rebuild, because the image is prebuilt upstream.

If you prefer the archive route, the README's prebuilt section downloads release.zip from the Releases page and runs it under Node. Note that this path runs the server with Node's CommonJS server.js entry and expects Node on the host; the root package.json declares engines.node >=20 and packageManager [email protected], which is the floor for the source build rather than the archive.

cd standalone
vim .env # 配置环境变量
export PORT=2323
node server.js

Either way, the first real use is the same: point the environment at your Mix Space Core 10.x instance, start the container or the Node process, and confirm the homepage renders posts pulled from the API rather than a static shell.

Where Shiro stops being the right tool

The version pin is the hardest limitation. Shiro requires Mix Space Core == 10.x and is incompatible with higher versions. If your Core instance moves ahead, you are outside the supported combination, and because the README says only critical bugs are fixed, you should not expect the frontend to catch up. That is a frozen pair, not a moving target.

Maintenance mode also means the feature set you see is the feature set you get. The README names a separate paid build, Shiroi, that carries AI summaries and translation, WebGPU snow effects, Passkey authentication, a Lexical comment editor, a dashboard and OpenPanel analytics. None of that is in this repository. If any of those items is on your requirements list, Shiro is the wrong starting point and the README says so by pointing to Shiroi and to Yohaku.

There is a practical failure mode in the build too. The Dockerfile downloads specific font files from GitHub releases during the image build, so a build environment without outbound access to that host will fail before the app compiles. The same file notes that build-time secrets must be passed securely, which means anyone building their own image inherits that responsibility.

Shiro against a general-purpose blog framework

The obvious alternative is not another Mix Space theme but a general-purpose framework where the frontend owns the content model: Astro, Hugo, or a hand-rolled Next.js site reading from a headless CMS. The difference is where the data lives. Shiro is a presentation layer over Mix Space Core, and the API shape is fixed by that backend; the Dockerfile hardcodes NEXT_PUBLIC_API_URL to ${BASE_URL}/api/v2. A Hugo or Astro site owns its content files and its routes, and can be deployed as static output with no server process. Shiro's compose file runs a long-lived Node container on port 2323, and its realtime features depend on Socket.IO connections that static hosting cannot provide.

Within the same ecosystem, Yohaku is the alternative the README itself names, described as an independent project with a new design language and visual system, with full code access tied to sponsorship. That is a different trade: a newer, differently licensed codebase in exchange for leaving a frontend that is explicitly frozen. Shiroi sits in the same family as a paid upgrade rather than a replacement, adding the AI, visual and dashboard features that Shiro does not carry.

Licence, updates and what maintenance mode costs you

The README states the project uses the AGPLv3 licence with additional commercial conditions, and that use requires following ADDITIONAL_TERMS.md. Both files are at the repository root. The repository metadata reports the licence as NOASSERTION, which is consistent with a licence that is not a plain SPDX identifier once additional terms are attached. Anyone deploying a public site should read ADDITIONAL_TERMS.md directly; this is a description of what the repository says, not legal advice, and the terms are the terms.

Upgrade cost is low in one direction and zero in the other. Because the image is prebuilt, updating is docker compose pull followed by a restart, and the compose file's restart: always policy keeps the container up. But the README says Shiro stays at the current version with no new features, so pulling a newer image does not buy you new capability, only fixes. The release history reflects that pace: v1.2.5 in January 2025, v1.2.3 in October 2024, v1.2.2 earlier that same month. The last push to the repository was on 2026-09-22, so the code is touched, but the README's own statement about scope is the better guide to what those touches contain.

Editorial conclusion

Adopt Shiro if you already run Mix Space Core 10.x and want a finished, opinionated frontend without writing one. Do not adopt it if you are starting fresh or need features that will keep arriving: the README states the project stays at its current version and only critical bugs get fixed, and Yohaku is the successor. Before committing, verify your Mix Space Core version is exactly 10.x, read ADDITIONAL_TERMS.md alongside the AGPLv3 licence, and confirm which pieces you need are in the paid Shiroi build rather than here.

Frequently asked questions

Official sources

1. Innei/Shiro on GitHub
2. Issues
3. Project website
4. README
5. Releases