🌸 Haru — A Live2D Anime Companion

相原ハル ・ Your interactive 2D anime "wife", living in the browser

A high-performance, SEO-optimized, multi-language single-page site featuring a real Live2D Cubism model that follows your cursor, blinks, breathes, and changes expression — built with Astro, in 7 languages, shipping only ~8 kB gzipped on first load. 💗

---

⭐ If this project makes you smile, please give it a star — it genuinely helps!

✨ Overview

Meet Haru (ハル) — a genuine Live2D Cubism 4 model rendered with pixi-live2d-display and PixiJS. She's not a static image or a CSS trick: she's a real rigged VTuber-style model that reacts to you in real time.

The engineering challenge — and what makes this repo worth studying — is that Live2D is heavy (a WebGL runtime plus a ~2 MB model). This project proves you can wrap that in a page that is still fast and ranks well, by prerendering everything to static HTML and lazy-loading the runtime completely off the critical path.

🎬 Live demo & preview

👉 topshopifydev.github.io/wife-2d-anime

Move your mouse — Haru follows you. Click her for a motion. Try the mood buttons and the 🌐 language menu.

💡 Tip: after you push, add a screenshot or GIF here (e.g. docs/preview.gif) — repos with a visual get far more stars.

🌟 Highlights

🎭 Real Live2D model	Genuine Cubism 4 rig — cursor tracking, auto-blink, breathing, hair physics, 8 expressions, tap/idle motions
⚡ Blazing fast	Static prerender + lazy WebGL runtime → ~4 kB JS + inlined CSS on first paint
🔍 SEO-first	Full metadata, Open Graph, Twitter cards, JSON-LD, sitemap, robots, canonical URLs
🌍 7 languages	Separate prerendered page per language with hreflang — the search-engine-correct way
🌗 Light / dark theme	"Sakura" & "Night", persisted to localStorage
🎀 Delightful details	Falling sakura petals, typewriter intro, speech bubbles, and a hidden Konami-code surprise
📱 Responsive & a11y	Phone → ultrawide, semantic HTML, prefers-reduced-motion respected
🧩 Zero-dependency runtime	Cubism Core, PixiJS & the model are vendored — works offline, no CDN calls

🛠️ Tech stack

Layer	Choice	Why
Framework	Astro 5	Ships zero JS by default; prerenders static HTML — ideal for SEO + performance
Character	Live2D Cubism 4 + pixi-live2d-display + PixiJS 6	A real, animated 2D model — not an image
i18n	Astro i18n routing + a single translations table	One crawlable URL per language, auto hreflang
Styling	Hand-written CSS (system fonts, CSS variables)	No webfont cost, no CLS, tiny
Images	sharp build script	Generates the OG image + PWA icons from SVG

🔍 SEO & ⚡ performance

• Prerendered static HTML with real, crawlable content (<h1>, profile, features, FAQ) — not an empty canvas
• <title>, meta description, canonical, robots, Open Graph + Twitter Card (with a generated 1200×630 og.png)
• JSON-LD structured data (WebSite, Person, FAQPage → rich-result eligible) — localized per language
• Sitemap (@astrojs/sitemap), robots.txt, PWA manifest.webmanifest + maskable icons
• Multi-language SEO: one URL per language, reciprocal hreflang + x-default, per-locale lang / og:locale / inLanguage
• Critical JS ~4.4 kB; the heavy Live2D runtime is lazy-loaded via IntersectionObserver + requestIdleCallback
• CSS inlined (no render-blocking stylesheet) · system fonts (no download, no layout shift)

🌍 Languages

Seven languages, each a separate static page with reciprocal hreflang alternates:

🇯🇵 日本語 → / (default)	🇬🇧 English → /en/	🇪🇸 Español → /es/
🇩🇪 Deutsch → /de/	🇹🇷 Türkçe → /tr/	🇵🇹 Português → /pt/
🇨🇳 中文 → /zh/

A globe menu switches languages with plain links (works without JS). All strings live in one file — src/i18n/translations.js.

Add a language: add its code to src/i18n/config.js and a matching entry in translations.js. The route, sitemap, and hreflang alternates generate automatically.

🚀 Quick start

git clone https://github.com/topshopifydev/wife-2d-anime.git
cd wife-2d-anime
npm install

npm run dev       # dev server  → http://localhost:4321
npm run build     # static build → dist/
npm run preview   # preview the production build

⚠️ Before deploying, set site in astro.config.mjs and the URL in public/robots.txt to your final domain — they feed canonical URLs, the sitemap, and Open Graph tags.

Regenerate the OG image / icons after editing scripts/og.svg:

node scripts/gen-assets.mjs

📁 Project structure

wife-2d-anime/
├── astro.config.mjs           # site URL, i18n, sitemap, CSS inlining
├── src/
│   ├── layouts/Base.astro     # SEO <head>: meta, OG, hreflang, JSON-LD, theme
│   ├── components/Page.astro  # the whole localized page + lazy Live2D loader
│   ├── pages/
│   │   ├── index.astro        # default locale (ja) at /
│   │   └── [locale]/index.astro   # /en/, /es/, /de/, /tr/, /pt/, /zh/
│   ├── i18n/
│   │   ├── config.js          # locale list, hreflang / og:locale maps
│   │   └── translations.js    # all UI strings for every language
│   └── styles/global.css      # theme, layout, petals, language menu
├── public/
│   ├── vendor/                # Cubism Core, PixiJS, pixi-live2d-display (bundled)
│   ├── assets/live2d/haru/    # the Haru Cubism model (moc3, textures, motions…)
│   └── og.png · icon-*.png · favicon.svg · manifest.webmanifest · robots.txt
└── scripts/                   # og.svg + gen-assets.mjs (raster OG/icons via sharp)

🎨 Make it yours

Change…	Where
Use a different Live2D model	drop it in public/assets/live2d/…, set MODEL_URL in src/components/Page.astro
Any text, in any language	src/i18n/translations.js (name, tagline, dialogue, profile, features, FAQ)
Add / remove a language	src/i18n/config.js + translations.js (see Languages above)
Which expression each mood plays	moods array in translations.js (exp / motion per entry)
Colors & theme	CSS variables in src/styles/global.css

🌐 Deploy

GitHub Pages (great for a portfolio piece):

1. npm run build, then publish dist/ with actions/deploy-pages.
2. For a project page at topshopifydev.github.io/wife-2d-anime/, set base: '/wife-2d-anime/' in astro.config.mjs or deploy from a repo named topshopifydev.github.io to serve it at the root (simplest — the absolute asset paths just work).

Vercel / Netlify / Cloudflare Pages — zero config: build npm run build, output dist. (Astro is auto-detected.)

🙏 Credits & licensing

• Code (this repo): MIT — free to use, remix, and share.
• Live2D Cubism Core — © Live2D Inc., under the Live2D Cubism Core License.
• Haru model (public/assets/live2d/haru/) — a Live2D sample model, © Live2D Inc., under the Live2D Free Material License. Review Live2D's terms before commercial use and keep the copyright notice.
• PixiJS — MIT · pixi-live2d-display by guansss — MIT.

Not affiliated with or endorsed by Live2D Inc.

👤 Author

Sid Lukkassen

If you build something with this, I'd love to see it — open an issue or mention me. 🌸

---

Enjoyed it? Drop a ⭐ — it means a lot and helps others discover the project.

Made with 💗 & Astro by Sid Lukkassen · おかえりなさい〜 🌸