DEV Community

Jaroslav Svetlik
Jaroslav Svetlik

Posted on

How We Built StackBriefly as a Headless WordPress and Next.js Publication

#webdev #nextjs #wordpress

When we started StackBriefly, the goal was simple: build a practical software
publication where the editorial workflow stayed easy, but the public site still
felt fast, structured, and maintainable.

The setup we chose is a common pattern, but the details matter:

  • WordPress runs as the editorial backend.
  • Next.js renders the public site.
  • The public domain is separate from the CMS subdomain.
  • Deploys use timestamped release folders with an atomic current symlink.
  • Old release folders are pruned so server backups do not grow forever.

StackBriefly is live at stackbriefly.com.

Why not just use WordPress on the public domain?

WordPress is still a very good writing and editorial tool. The admin experience
is familiar, media uploads are straightforward, and publishing content does not
require a developer every time.

But for the public frontend, we wanted more control over:

  • HTML structure
  • metadata
  • structured data
  • sitemap generation
  • article templates
  • category archives
  • pagination
  • performance
  • deployment rollback

That made a headless setup a better fit.

The CMS lives on a subdomain and the public site is rendered by Next.js. That
keeps editorial work inside WordPress while giving the frontend a predictable
application structure.

What the public site handles

The Next.js app handles the public reading experience:

  • homepage
  • blog archive
  • paginated archive pages
  • article pages
  • category pages
  • topics page
  • sitemap
  • RSS feed
  • canonical URLs
  • Open Graph metadata
  • breadcrumb structured data

The public site is intentionally not a marketing landing page. It is a software
publication, so the layout is built around scannable topics, latest articles,
and practical comparison guides.

One of the most useful pages for us is the SEO category:

StackBriefly Next.js and SEO guides

WordPress stays focused on publishing

WordPress is used for:

  • post editing
  • categories
  • featured images
  • excerpts
  • authorship
  • media library
  • publishing status

The frontend reads from the WordPress REST API and normalizes the data into a
smaller shape for the Next.js app.

For a small editorial project, this is enough. GraphQL can be useful later, but
the REST API keeps the first version simple and reduces moving parts.

The deployment detail that mattered more than expected

One issue we hit was not a framework issue. It was a server operations issue.

The first release layout kept every full Next.js release under the aaPanel site
root. Each release included node_modules and build artifacts, so backups grew
quickly. The fix was to move complete releases outside the web root:

/www/app-releases/stackbriefly.com/releases/<timestamp>
Enter fullscreen mode Exit fullscreen mode

The public root keeps only lightweight files and a symlink:

/www/wwwroot/stackbriefly.com/current
Enter fullscreen mode Exit fullscreen mode

Deploys now follow this pattern:

  1. Create a new timestamped release folder.
  2. Upload source without .git, .next, or node_modules.
  3. Run npm ci and npm run build on the server.
  4. Switch the current symlink atomically.
  5. Restart the Next.js service.
  6. Prune old releases and remove .next/cache from kept releases.

This gave us rollbacks without letting backup size grow without control.

I wrote more about that VPS deployment pattern here:

Deploying a Next.js blog on a VPS with Nginx, systemd, and rollbacks

What we learned from Search Console

The technical setup was not the whole SEO story.

Search Console started showing impressions before meaningful clicks. That told
us the site was discoverable, but not trusted or ranked strongly enough yet.

The main lessons:

  • Publishing more pages is not automatically better.
  • Internal links matter when a site has many new category pages.
  • Old 404s should be redirected when Search Console keeps reporting them.
  • A sitemap can be valid while Google still delays crawling many URLs.
  • A new site with no external references usually needs patience and legitimate mentions before rankings move.

So instead of blindly publishing more articles, we started focusing on the
clusters that already had impressions. For StackBriefly, that meant topics like
localization management, privacy compliance, sales tax automation, accessibility
compliance, social listening, data integration, and mobile device management.

Why this setup still feels worth it

The biggest advantage is separation of concerns.

Editors can write in WordPress. The frontend can stay focused on rendering,
metadata, structured data, and performance. Deployments can be handled like an
application instead of a shared mutable folder.

The tradeoff is operational responsibility. You need to own:

  • revalidation
  • deployment
  • redirects
  • sitemap quality
  • CMS availability
  • media URLs
  • backup size
  • monitoring

For a serious content project, that tradeoff is acceptable. For a quick blog
with no technical owner, normal WordPress hosting would be simpler.

Bottom line

A headless WordPress and Next.js setup is not automatically better than
WordPress alone. It becomes useful when the project needs editorial convenience
and application-level control at the same time.

For StackBriefly, that balance made sense. The next challenge is not just
shipping more content. It is improving the pages that already show search
signals, cleaning up indexing issues, and earning a few legitimate references
from relevant places.

Top comments (0)