Building a massive ecosystem requires serious organization. At Heavstal Tech™, our platform has rapidly expanded to include over 30+ REST APIs, a fully-fledged OAuth2 Identity Provider, Zero-Knowledge Password Managers, and complex NPM modules like our WhatsApp heavstal-auth wrapper.
Up until recently, our documentation was tightly coupled within our main Next.js application. But as our platform grew, so did our problems.
Today, I am thrilled to announce Heavstal Docs — our brand new, standalone documentation portal built with Astro 6 and Starlight.
Here is a look at why we made the switch and how we engineered it.
The Problem with Monolithic Docs
Initially, serving our API documentation from our main Next.js API Gateway seemed like a good idea. We were parsing Markdown on the fly, rendering syntax highlighting via CodeMirror, and trying to handle complex routing.
However, we quickly ran into bottlenecks:
-
Bloated Bundle Sizes: Shipping heavy markdown parsers (like
markedandprismjs) to the client just to render text didn't make sense. - Build Times: Statically generating dozens of deep technical guides slowed down our CI/CD pipeline for the main API dashboard.
- Separation of Concerns: A high-performance API Gateway and User Console shouldn't share the same compute resources as static documentation pages.
The Solution: Astro + Starlight
We decided to rip the documentation out of the Next.js app entirely and move it to a dedicated sub-domain using Astro and Starlight.
Why Astro? Zero JavaScript by default.
It ships pure, blazing-fast HTML, which is exactly what a documentation site needs. Coupled with Starlight and Tailwind CSS v4, we got dark mode, mobile-responsive sidebars, and full-text search practically out of the box.
What You'll Find in Heavstal Docs
Whether you are a hobbyist or an enterprise developer, the new portal has everything you need to plug into our infrastructure:
- The API Reference: Step-by-step guides for all 30+ endpoints, including our AI Generators, Media Downloaders (TikTok/X), Web Scrapers, and Cryptography tools.
- Heavstal Accounts (OAuth2): Learn how to integrate "Sign in with Heavstal" into your Next.js or Python apps using our OIDC-compliant identity service.
- NPM Modules: Deep dives into our enterprise-grade packages.
- Bot Engineering: Guidelines and rules for deploying automation agents on our network.
Check It Out
By decoupling our docs, our main Next.js console is now leaner, faster, and strictly focused on API management and security, while our documentation gets the SEO and readability benefits it deserves.
Explore the new docs here: heavstal-docs.vercel.app
Get your free API key: heavstal-tech.vercel.app
Let me know what you think in the comments! Are you team monolithic docs or decoupled docs?
Top comments (0)