Fuwari: an Astro blog template with Pagefind search and Svelte islands

The problem Fuwari solves for a writer who does not want to build a blog

Starting a static blog with Astro means writing layouts, a post collection schema, a table of contents, an RSS route, a sitemap and a search index before you publish anything. Fuwari is a template that already contains those parts, so the first commit can be a post rather than a layout. The README lists the features as animations and page transitions, light and dark mode, customizable theme colors and banner, responsive design, Pagefind search, extended Markdown, a table of contents and an RSS feed.

The intended user is someone who writes in Markdown and is comfortable running a few terminal commands, but does not want to design a theme. The repository is a template rather than a package you install into an existing site: the README tells you to generate a new repository from the template or fork it, and then clone that repository locally. That distinction matters. You are taking ownership of the source, not depending on an upstream theme that updates underneath you.

The trade-off is visible in the dependency list. Fuwari pulls in Svelte through @astrojs/svelte, KaTeX for math, PhotoSwipe for image viewing, OverlayScrollbars, Swup for page transitions, and a set of Iconify icon packs. That is a lot of surface area for a blog. If you wanted a minimal Astro blog with no client-side JavaScript beyond what Astro ships, this template is not that.

How Fuwari is put together: Astro pages, Svelte components and a Pagefind index

The build is an Astro static site. Pages and layouts live under src/, posts are Markdown files in src/content/posts/, and the site is generated into ./dist/. The package.json build script is two commands chained together: astro build, then pagefind --site dist. Pagefind runs after the HTML exists, which is why search works on a purely static site with no search server. The index is generated at build time from the rendered pages.

Interactivity comes from Svelte. The @astrojs/svelte integration is pinned at 7.2.3 in package.json, and the repository has a svelte.config.js at the top level. Astro ships Svelte components as islands, so only the components that need to be interactive are hydrated. The theme also uses @swup/astro for page transitions, which is a client-side navigation layer rather than a framework feature.

Markdown is processed through a longer pipeline than default Astro. The dependencies include remark-directive, remark-directive-rehype, remark-github-admonitions-to-directives, rehype-slug, rehype-autolink-headings, rehype-katex, rehype-components and markdown-it. The README describes three extended features that come out of this: admonitions, GitHub repository cards, and enhanced code blocks through Expressive Code with the collapsible-sections and line-numbers plugins. KaTeX is present in the dependency list, so math typesetting is part of the pipeline even though the README's feature list does not call it out.

Configuration is centralised. Site settings live in src/config.ts, deployment settings live in astro.config.mjs, and pagefind.yml sits at the repository root for the search step. A vercel.json is also present, which is a hint about the deployment target the author uses, though the README points to Astro's own deploy guides for Vercel, Netlify and GitHub Pages generally.

Installing Fuwari and publishing a first post

The README gives two routes to a starting repository. You can generate a new repository from the template on GitHub or fork it, or you can scaffold with a package manager. The scaffold commands are listed for npm, Yarn, pnpm, Bun and Deno.

pnpm create fuwari@latest

After the repository exists locally, install dependencies. The README states that pnpm is required, and package.json enforces this with a preinstall script that runs npx only-allow pnpm, so npm install and yarn install will be rejected.

pnpm install

The README notes that pnpm itself can be installed with npm install -g pnpm. The badges at the top of the README state Node.js >= 20 and pnpm >= 9, so check your Node version before installing. Next, edit src/config.ts to set the site title, theme colors and banner. Then create a post.

pnpm new-post <filename>

That script is node scripts/new-post.js, and it writes a file into src/content/posts/. The README documents the frontmatter fields. A minimal post looks like this.

---
title: My First Blog Post
published: 2023-09-09
description: This is the first post of my new Astro blog.
image: ./cover.jpg
tags: [Foo, Bar]
category: Front-end
draft: false
lang: jp
---

The lang field is only needed when a post's language differs from the site language set in config.ts. To see the result, start the dev server. The README states it runs at localhost:4321.

pnpm dev

Before deploying, run the build. This is the step that also produces the Pagefind index, so a build failure here usually means the search index will be missing.

pnpm build

Finally, the README says you need to edit the site configuration in astro.config.mjs before deployment, and it links to Astro's deploy guides for Vercel, Netlify and GitHub Pages. There is also pnpm preview for checking the built output locally before it goes anywhere.

Where Fuwari gets in the way: pnpm lock-in, build coupling and no CMS

The preinstall guard is the first constraint you meet. Because package.json runs npx only-allow pnpm before installation, anyone on a team that standardises on npm or Yarn cannot install the project without editing package.json. That is a deliberate choice by the template author, and it is defensible for a template that ships a pnpm-lock.yaml, but it is friction if your CI image or your colleagues are set up differently.

The second constraint is the build script. Search is not a plugin that degrades gracefully; it is a second command appended to the build. If Pagefind fails or the dist directory is not where it expects, the build fails or the site ships without a working search box. The repository has a pagefind.yml, so the indexing behaviour is configurable, but the README does not document what that file controls or how to exclude pages from the index.

Third, there is no content management layer. Posts are Markdown files with frontmatter, created by a Node script. There is no admin UI, no draft preview workflow beyond the draft: false flag, and no editorial review step. If a non-technical author needs to publish without touching Git, this is the wrong tool. The same applies to anyone who needs server-side rendering, authenticated routes or a database: the output is a static site in ./dist/, and the deployment guides the README points to are static hosting guides.

The dependency surface is the fourth thing to weigh. Astro is pinned at 5.13.10 rather than a caret range, so a major Astro upgrade is a manual edit. Around it sit Svelte, KaTeX, PhotoSwipe, Swup, OverlayScrollbars and several Iconify icon sets. Each is a package you will need to keep current, and the README does not describe an upgrade procedure or a supported version matrix beyond the Node and pnpm badges.

Fuwari compared with a plain Astro blog or a component-based theme

The closest alternative is Astro's own blog starter, which the Astro documentation describes as a minimal starting point. The difference is scope. A plain Astro blog gives you a content collection, a layout and an RSS route, and leaves search, code block styling, image lightboxes and page transitions to you. Fuwari arrives with those decisions already made: Pagefind for search, Expressive Code for code blocks, PhotoSwipe for images, Swup for navigation. You trade a smaller dependency tree for less setup work.

The second comparison is with themes distributed as npm packages that you add to an existing Astro project. Fuwari is not that. The README instructs you to generate a repository from the template or fork it, which means the theme code becomes your code. Upstream changes do not arrive through a package manager; you merge them yourself or not at all. That is better for stability and worse for receiving fixes.

A third point of comparison is the search implementation. Many static blog themes either omit search or add a client-side index built from a JSON file shipped with the site. Fuwari uses Pagefind, which indexes the built HTML and serves results from a generated index. The practical difference is that the index reflects what was actually rendered, including content generated by components, rather than a hand-maintained list of posts. The cost is that the index only exists after a successful build.

Maintenance cost, licence and what to check before you commit

Fuwari is MIT licensed, and the repository contains a LICENSE file at the top level alongside a FOSSA licence badge in the README. MIT is permissive: you can use the template commercially, modify it and redistribute it, provided the copyright notice and permission notice are retained. That applies to Fuwari's own code. It does not automatically cover the assets you add, such as a banner image or a font you download yourself, and the dependency list includes packages under their own licences. If licence compatibility matters to your organisation, the FOSSA project linked from the README is the place to check the transitive picture. Nothing here is legal advice.

On maintenance, the last push to the repository was on 2026-03-10. The repository is not archived. There are no releases listed, and package.json still carries version 0.0.1, so upgrades are not distributed as tagged releases you can track. Plan to follow the main branch and to test Astro upgrades yourself, since astro is pinned at 5.13.10 rather than a range.

The upgrade cost is concentrated in three files: package.json for dependency versions, astro.config.mjs for the site and deployment configuration, and src/config.ts for theme settings. Because the theme code is yours after forking, an upstream change to a layout or a component will not merge cleanly if you have edited it. Before adopting, run pnpm build to confirm the Pagefind step completes in your environment, and open src/config.ts to see whether its options cover the customisation you need.

Editorial conclusion

Adopt Fuwari if you want a pre-styled Astro blog and are willing to run pnpm on Node 20 or newer. Do not adopt it if you need a CMS, server-side rendering, or a dependency set you can audit quickly. Before committing, run pnpm build locally to confirm the Pagefind indexing step completes, and read src/config.ts to check that the theme options cover what your site needs.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. saicaca/fuwari on GitHub