DEV Community: Anton Makasin

Mobile-First SCSS Architecture with Dart Sass in Docker

Anton Makasin — Sun, 08 Nov 2026 06:00:00 +0000

Our SCSS is split into three folders and compiled by tools inside Docker, so developers do not need Sass installed on the host. The source and generated files still live on a bind-mounted project directory. Here's the setup and why it matters.

The Directory Structure

assets/scss/site/
├── common/          ← variables, breakpoints, shared partials
├── mobile/          ← base styles and small-screen adjustments
│   ├── _catalog_list.scss
│   ├── _catalog_item.scss
│   ├── _account.scss
│   └── _main.scss
└── desktop/         ← wider-screen overrides
    ├── _catalog_list.scss
    ├── _catalog_item.scss
    └── _main.scss

The mobile folder contains the base appearance. It still has a few targeted media and accessibility queries; “mobile-first” does not have to mean “no media queries.”

The desktop folder primarily contains wider-screen overrides. If a component does not change at the desktop breakpoint, it usually needs no matching desktop partial.

Why This Matters

The separation makes the cascade and ownership clear: base rules live in one place, and desktop files describe the delta. We compile separate outputs and apply the desktop stylesheet conditionally:

<link rel="stylesheet" href="/storage/static/css/site/main_catalog_list_mobile.css">
<link rel="stylesheet"
      href="/storage/static/css/site/main_catalog_list_desktop.css"
      media="(min-width: 641px) and (min-height: 500px)">

The media attribute controls when the desktop CSS applies. Browsers may fetch a nonmatching stylesheet at lower priority, but it does not guarantee that the file will not be downloaded. Verify transfer behavior with browser tooling instead of treating file separation as an automatic bandwidth saving.

Building Inside Docker

We never run sass on the host machine. The Docker container has Dart Sass installed:

# docker-compose.yml (simplified)
site:
  build:
    context: .
    dockerfile: .docker/site/site.dockerfile
  command: ["make", "-f", "/Makefile", "dev"]
  volumes:
    - ./src:/app
    - ./Makefile:/Makefile

The development target builds assets once, then runs Air and Sass concurrently:

dev: build-css-dev build-js-dev
    $(MAKE) -j 2 run-air watch-css

run-air:
    cd $(SRC_DIR) && air -c .air.site.toml

watch-css:
    sass --watch --poll $(SCSS_INPUTS) --style=expanded --no-source-map

We use --poll because filesystem event delivery from bind mounts varies across host and Docker combinations. Polling is not universally required, so test both modes in your own environment.

Compiled Output

storage/static/css/site/
├── main_catalog_list_mobile.css
├── main_catalog_list_desktop.css
├── main_catalog_item_mobile.css
├── main_catalog_item_desktop.css
├── main_account_mobile.css
├── main_account_desktop.css
├── bundle_mobile.css
└── bundle_desktop.css

Our static web server serves the compiled files directly, without routing them through the Go application.

The Gotcha: Air Doesn't Watch SCSS

Air's config explicitly excludes assets/ and storage/:

[build]
  exclude_dir = ["assets", "storage", "tmp"]

This is intentional. SCSS changes are handled by sass --watch, which runs in parallel. If Air watched SCSS files too, it would rebuild the Go binary on every CSS edit — pointless and slow.

JavaScript has no watcher in this setup. After editing an entry file, we run:

docker compose exec -T site make -f /Makefile build-js-dev

This is a deliberate project trade-off, not a requirement of Docker or Sass.

What We'd Change

If starting over, we would evaluate native CSS plus Lightning CSS, or keep Sass and add a separate post-processing step. Lightning CSS can transform, prefix, bundle, and minify CSS, but it is not a drop-in compiler for SCSS syntax.

Dart Sass remains a good fit for the current partials, and keeping the toolchain in Docker gives every developer the same compiler version.

This article is based on lessons from building Towami, a multi-country marketplace and white-label storefront platform. Follow for more practical notes on Go, HTMX, infrastructure, and SaaS.

HTMX + Alpine.js: Building a SPA Feel Without a Client-Rendered App

Anton Makasin — Tue, 03 Nov 2026 01:30:00 +0000

Our marketplace uses no React, Vue, or Svelte application. Most of the interactive UI is HTMX and Alpine.js layered on server-rendered HTML. Alpine is a JavaScript framework, but it does not turn the site into a client-rendered SPA.

The Principle

Every navigable page URL can return a complete page rendered with Go and Templ. HTMX progressively enhances navigation by replacing fragments. Alpine.js handles local UI state such as dropdowns and modals.

There is no virtual DOM or hydration step. We still copy or minify our JavaScript for deployment, and an isolated rich-text editor has its own bundle; HTMX and Alpine do not require a framework-specific compile pipeline.

HTMX Navigation: Catalog Example

The catalog keeps an ordinary GET form. Global hx-boost progressively enhances links and forms, while the inherited target replaces the page's main content:

<body hx-boost="true"
      hx-target="#main-content"
      hx-swap="innerHTML transition:true show:window:top">
  <main id="main-content">
    <form method="get" action="/en/vehicles/cars/for-sale">
      <select name="brand">
        <option value="">All brands</option>
        <option value="toyota">Toyota</option>
      </select>
      <button type="submit">Apply</button>
    </form>
    <!-- Server-rendered catalog cards -->
  </main>
</body>

Without JavaScript, the form performs normal navigation. With HTMX, hx-boost sends an HX-Request header and swaps #main-content. The same URL remains directly navigable and crawlable.

The form does not hardcode hx-push-url. When query facets can be represented by a canonical path, the server returns the HTMX response with HX-Push-Url; a normal request receives the corresponding redirect. This keeps URL normalization at the HTTP boundary instead of duplicating it in browser code.

Alpine.js: Client-Side State

Alpine handles interactions that do not need a server round trip:

<!-- Mobile menu toggle -->
<div x-data="{ open: false }">
    <button @click="open = !open"
            :aria-expanded="open.toString()"
            aria-controls="mobile-menu">
        Menu
    </button>
    <nav id="mobile-menu" x-show="open" x-transition>
        <!-- menu items -->
    </nav>
</div>

Our Alpine components are registered from a plain JavaScript file. That is a project choice, not an Alpine requirement.

Notifications via HTMX Triggers

When a server action completes, it can send a small UI event through an HTMX response header. The public and account UI uses show-flash (the admin UI has an analogous show-toast event):

func SendSiteFlash(c *gin.Context, message string, isError bool) {
    payload := map[string]any{
        "show-flash": map[string]any{
            "message": message,
            "error":   isError,
        },
    }
    data, _ := json.Marshal(payload)
    c.Header("HX-Trigger", ToHeaderASCII(string(data)))
}

On the client, Alpine listens for the event and updates an accessible status element:

<div x-data="{ msg: '', err: false, show: false }"
     @show-flash.window="msg = $event.detail.message; err = !!$event.detail.error; show = true"
     x-show="show"
     :role="err ? 'alert' : 'status'">
  <span x-text="msg"></span>
</div>

JSON encoding protects the header's structure, while ASCII conversion keeps the HTTP header transport-safe. Neither step makes sensitive provider errors suitable for users, so map those to controlled messages first and keep header payloads small.

Why This Stack?

Progressive enhancement. Important content and links exist in server-rendered HTML.
A smaller client runtime. We ship only the libraries and custom behavior the page needs. The actual payload should be measured, not assumed.
A direct mental model. The server returns HTML, HTMX swaps it, and Alpine owns small pockets of local state.

Complex client-side interactions can still justify a focused library. We use a rich-text editor as an isolated module rather than making the entire site a client application.

One boundary matters: Alpine validation is only a usability enhancement. Authorization and input validation still belong on the server.

This article is based on lessons from building Towami, a multi-country marketplace and white-label storefront platform. Follow for more practical notes on Go, HTMX, infrastructure, and SaaS.

Why We Chose Templ Over html/template (and What We Learned)

Anton Makasin — Tue, 27 Oct 2026 06:00:00 +0000

Go's standard html/template works well. It is in the standard library, is well documented, and provides contextual escaping. We used it before switching to Templ. Here's why.

The Problem With html/template

As the codebase grew, we hit recurring issues:

Template mistakes surface at runtime. Write {{.Titl}} instead of {{.Title}} and template execution returns an error. It is not normally a panic, but it is still later feedback than a compiler error.
Weaker editor support. Support varies by editor and plugin, but field completion, navigation, and refactoring are less reliable across the boundary between Go and template text.
Runtime data contracts. The template expects particular fields and methods, but the Go compiler does not type-check those references. Rename a field and tests—or a request that executes the template—must catch it.

What Templ Gives Us

Templ files use their own Go-like syntax. The generator turns them into Go source, so component parameters and expressions are type-checked:

// templates/card.templ
templ CatalogCard(card CatalogCardView) {
    <article class="card">
        <img src={ card.Image } alt={ card.Title } />
        <h3>{ card.Title }</h3>
        <span class="price">{ FormatPrice(card.Price, card.Currency) }</span>
    </article>
}

If CatalogCardView has no Title field, generation or compilation fails. If FormatPrice changes its signature, compilation fails. Templ's editor tooling also provides syntax support and autocomplete; the file itself is not literally ordinary Go.

The Generation Step

Templ generates *_templ.go files from .templ files. This extra step is the main friction point:

templ generate

Never edit generated files manually: the next generation will overwrite them.

Multi-Container Deduplication

Several development services share the same bind-mounted templates. Letting each process generate the same output is redundant and creates concurrent writers. Our pre-build hook resolves the repository root, checks sources under internal/ and cmd/, and checks for missing generated outputs. It performs the check both before and after acquiring one shared lock:

#!/bin/sh
set -eu

ROOT=$(CDPATH= cd -- "$(dirname "$0")/.." && pwd)
STAMP_DIR="$ROOT/.dev"
STAMP="$STAMP_DIR/templ.stamp"
LOCK="$STAMP_DIR/templ.lock"
mkdir -p "$STAMP_DIR"

needs_generate() {
  [ ! -f "$STAMP" ] && return 0

  newer=$(find "$ROOT/internal" "$ROOT/cmd" \
    -name '*.templ' -newer "$STAMP" -print -quit 2>/dev/null || true)
  [ -n "$newer" ] && return 0

  missing=$(find "$ROOT/internal" "$ROOT/cmd" -name '*.templ' -print 2>/dev/null |
    while IFS= read -r src; do
      out=$(dirname "$src")/$(basename "$src" .templ)_templ.go
      if [ ! -f "$out" ]; then
        echo yes
        break
      fi
    done || true)
  [ -n "$missing" ]
}

needs_generate || exit 0
exec 9>"$LOCK"
flock -w 180 9
needs_generate || exit 0

cd "$ROOT"
templ generate
touch "$STAMP"

The second check matters: another container may have generated the files while this process waited. Missing-output detection also recovers from a deleted *_templ.go even when no source timestamp changed.

What We Learned

Automate the generation step. Treat it like protobuf code generation: run it consistently and never hand-edit the output. Whether generated files belong in version control is a team decision; we commit them so builds do not depend on generation happening implicitly.

Templ + HTMX is a natural pair. Templ components return HTML fragments. HTMX swaps HTML fragments. No JSON serialization layer needed:

templ SearchResults(cards []CatalogCardView) {
    for _, card := range cards {
        @CatalogCard(card)
    }
}

The handler renders the component and returns it as an HTMX response. The browser swaps the fragment, with no client-side rendering layer.

Compile-time feedback scales well. A renamed field now fails generation or compilation instead of waiting for the affected template path to execute.

This article is based on lessons from building Towami, a multi-country marketplace and white-label storefront platform. Follow for more practical notes on Go, HTMX, infrastructure, and SaaS.

Targeting 100/100 PageSpeed: Our Critical CSS Inlining Strategy

Anton Makasin — Thu, 22 Oct 2026 19:32:00 +0000

Our stretch target is a 100 PageSpeed score on merchant storefronts. A score is not a guarantee—it varies by page, data, device, network, and Lighthouse version—but the target forces us to keep the render path small.

The Problem With One Big CSS File

A render-blocking styles.css can delay the first paint while the browser downloads, parses, and applies the rules needed for the page. For a marketplace with catalog pages, account dashboards, rich text editors, and storefronts, one shared file can grow quickly.

Our Three-Tier CSS Strategy

We split CSS into three categories based on when it's needed:

1. Inlined Route CSS

The shared layout inlines its base styles, and public routes inline a small route-specific stylesheet in the server-rendered response:

@templ.Raw("<style>" + assets.GetMainCSS("catalog_list_mobile.css") + "</style>")
@templ.Raw(helper.DesktopStyle(
    assets.GetMainCSS("catalog_list_desktop.css"),
))

This removes an external request from the initial rendering path. These files are route styles, not automatically generated "above-the-fold" subsets, so we still inspect their size and contents.

2. File-Linked CSS (account pages)

Account pages change frequently and benefit less from duplicating CSS in every HTML response, so they use cacheable stylesheets:

<link rel="stylesheet" href="/storage/static/css/site/main_account_mobile.css">

3. Lazy-Loaded Bundles (everything else)

Non-critical shared CSS — such as the footer, lightbox, and secondary catalog UI — loads asynchronously. Editor styles currently live in the linked account stylesheet:

<link rel="stylesheet" href="/storage/static/css/site/bundle_mobile.css"
      media="print" data-media="all"
      onload="this.media=this.dataset.media;this.onload=null">
<noscript>
  <link rel="stylesheet" href="/storage/static/css/site/bundle_mobile.css">
</noscript>

The media="print" pattern keeps the stylesheet from blocking initial screen rendering; once loaded, the handler changes its target media to all. The noscript fallback matters, and content must remain usable before the bundle arrives. This technique is suitable only for genuinely non-critical CSS.

Mobile-First File Structure

scss/
├── mobile/       ← base styles and small-screen rules
├── desktop/      ← desktop overrides
└── common/       ← shared variables, mixins

Mobile CSS is the default. A helper wraps compiled desktop CSS in the project's desktop media query before inlining it. The deferred desktop bundle also has a media target. This prevents desktop rules from applying on small screens, but it does not guarantee that mobile browsers never download those bytes.

Each page section compiles to separate files:

compiled-css/
├── main_catalog_list_mobile.css     ← inlined on catalog
├── main_catalog_list_desktop.css    ← inlined on catalog (desktop media)
├── main_account_mobile.css     ← linked on /account
├── main_account_desktop.css
├── bundle_mobile.css           ← lazy loaded
└── bundle_desktop.css

The Templ Integration

Our Go templates read the compiled CSS files while rendering. In development, that happens on every render for live reload; in production, the first successful read is cached in memory. Simplified:

func GetMainCSS(filename string) string {
    if production {
        return loadOnce(filename)
    }
    return readCompiledCSS(filename)
}

In the Templ layout:

@templ.Raw("<style>" + assets.GetMainCSS("catalog_list_mobile.css") + "</style>")

templ.Raw is safe here only because the input is trusted build output. Never pass merchant or user-controlled CSS through this path without a deliberate sanitization and isolation model.

There is no client-side CSS-in-JS. The essential CSS arrives with the HTML, while shared non-critical styles can still be cached as external files.

The Results

This design improves the mechanics that affect first render, but we do not treat an unrecorded Lighthouse run as evidence. We compare before/after builds with the same page data and throttling, track stylesheet and HTML byte sizes, and use field Core Web Vitals when enough traffic is available.

Inlining also has costs: repeated HTML bytes cannot use the browser's CSS cache, a large inline block can delay HTML transfer, and many entry points complicate builds. We monitor inline stylesheet and HTML sizes, move non-critical rules to external files, and re-measure as pages evolve. Defining an enforceable size budget is a useful next step.

This article is based on lessons from building Towami, a multi-country marketplace and white-label storefront platform. Follow for more practical notes on Go, HTMX, infrastructure, and SaaS.

Background Jobs in Go with Asynq: Emails, Notifications, and Resilience

Anton Makasin — Thu, 15 Oct 2026 17:58:00 +0000

When a customer places an order on a merchant's store, the checkout path does not call an SMTP server. After saving the order, it asks a mailer interface to enqueue a task in Redis.

Why Separate the Worker

Our worker binary is a dedicated process that pulls tasks from Redis queues using Asynq. It runs independently from the three HTTP binaries (site, shops, admin).

The reasoning is simple: SMTP latency is variable, and transient failures need retries. Neither concern should block the HTTP response. The worker can retry independently if the mail server is temporarily unavailable.

Task Architecture

Email delivery uses one generic task type and a template discriminator:

const TypeEmailDelivery = "email:deliver"

type EmailPayload struct {
    To       string         `json:"to"`
    Lang     string         `json:"lang"`
    Template string         `json:"template"`
    Data     map[string]any `json:"data"`
}

The producer marshals the payload and checks both operations:

payload, err := json.Marshal(EmailPayload{
    To:       recipient,
    Lang:     lang,
    Template: "new_shop_order",
    Data:     map[string]any{"OrderID": orderID},
})
if err != nil {
    return err
}
task := asynq.NewTask(TypeEmailDelivery, payload)
if _, err := client.EnqueueContext(ctx, task); err != nil {
    return err
}

The worker handles it:

func (h *EmailHandler) ProcessTask(ctx context.Context, t *asynq.Task) error {
    var p EmailPayload
    if err := json.Unmarshal(t.Payload(), &p); err != nil {
        return fmt.Errorf("decode email payload: %v: %w", err, asynq.SkipRetry)
    }
    return h.sender.Send(ctx, p)
}

Malformed JSON is permanent, so SkipRetry is appropriate. SMTP/network errors are returned normally and remain retryable.

What Lives in the Worker

Beyond order emails, the worker handles:

Email delivery — sign-up codes, password resets, support mail, orders, and inquiries
Telegram notifications — queued reports and alerts
Marketplace imports — longer, low-priority ingestion tasks

Each task type is registered with its own handler. The worker also uses weighted critical, default, and low queues. Those weights bias which queued task is selected next; they do not reserve workers, so long-running imports can still occupy the whole pool.

The Dev Gotcha

During local development, a queued email will not be sent unless both Redis and the worker are running. Use the project's documented service and log commands rather than copying production hostnames or credentials into an article.

docker compose up -d worker
docker compose logs worker

If the worker is down while Redis remains available, pending tasks can be processed after the worker restarts. That is not the same as guaranteed durability: data loss still depends on Redis persistence, replication, eviction policy, and backup configuration.

Retry Policy

Asynq retries failed tasks according to its retry policy. Short notification tasks use the standard policy, while imports run in a lower-priority queue with bounded retries and execution time. After retries are exhausted, Asynq archives the task. Monitor queue latency, retry counts, and archived tasks with tooling such as Asynqmon or your own metrics.

Asynq provides at-least-once execution, not exactly-once execution. A worker can complete a side effect and fail before acknowledging the task, so handlers must be idempotent. For email, a provider idempotency key or a database send ledger can prevent unwanted duplicates.

Why Not Just goroutines?

A bare go func() { sendEmail() }() has three structural problems:

Lost tasks on restart. A deploy kills the process and all in-flight goroutines die.
No retry. If SMTP is down for 5 minutes, all emails from that window are lost.
No visibility. A bare goroutine provides no queue, failure, or processing state to inspect.

Redis + Asynq gives us durable-enough queuing, retries, scheduling, and observability with little application code. The trade-offs are another stateful dependency and at-least-once semantics.

One final boundary matters: a database commit and a queue publication are separate operations unless the design explicitly bridges them. For business-critical delivery, use a transactional outbox in the same database transaction and publish it asynchronously.

Task payloads may contain email addresses or order details. Keep Redis on a private network with authentication and encryption as appropriate, minimize payloads and retention, and never log full payloads.

This article is based on lessons from building Towami, a multi-country marketplace and white-label storefront platform. Follow for more practical notes on Go, HTMX, infrastructure, and SaaS.

Our Layered REST Architecture in Go: Why GET Must Not Mutate Application State

Anton Makasin — Fri, 09 Oct 2026 23:50:00 +0000

We have a hard rule in our codebase: GET handlers never mutate application state. Incidental server-side effects such as access logging are compatible with HTTP's definition of a safe method, but a GET must not create, update, or delete an application resource. This matters even more when TLS 1.3 early data is enabled.

The 0-RTT Replay Problem

We use Cloudflare with 0-RTT Connection Resumption enabled. TLS 1.3 early data can reduce latency for a resumed connection, but early data does not have inherent replay protection. An attacker may capture and replay it.

Cloudflare supports 0-RTT for GET, HEAD, and OPTIONS requests and marks them with Early-Data: 1. That safe-method restriction reduces the surface; it does not make a side-effecting GET safe. A GET that increments a counter, creates a record, or marks a notification as read may run more than once.

The broader rule comes from RFC 9110's safe-method semantics: clients, crawlers, caches, and prefetchers may invoke GET without expecting state changes. 0-RTT is one reason to respect that contract, not the only reason.

Our Layered Approach

Layering and REST are separate ideas; this is the dependency flow we use for HTTP requests:

router → middleware → handler → service → repository → model/DB

Each layer has a clear role:

Layer	Responsibility
Router	URL → handler mapping
Middleware	Auth, country, locale, CSRF, rate limiting
Handler	Parse request, call service, return response
Service	Business logic, validation
Repository	SQL/GORM queries
Model	Database entity definitions

By convention, handlers do not import repositories directly and services do not construct SQL. Go does not enforce these boundaries automatically, so import checks, tests, and review are still useful. The payoff is that storage details can change without rewriting HTTP concerns.

Practical Enforcement

GET handlers depend on query-oriented service interfaces:

type CatalogQueries interface {
    List(context.Context, CatalogFilter) ([]CatalogCard, error)
}

func (h *CatalogHandler) List(c *gin.Context) {
    var filter CatalogFilter
    if err := c.ShouldBindQuery(&filter); err != nil {
        c.AbortWithStatusJSON(http.StatusBadRequest, gin.H{"error": "invalid filters"})
        return
    }

    cards, err := h.queries.List(c.Request.Context(), filter)
    if err != nil {
        c.AbortWithStatus(http.StatusInternalServerError)
        return
    }
    c.JSON(http.StatusOK, cards)
}

Publishing, editing, and deleting use POST, PUT, PATCH, or DELETE. Cloudflare does not accept those methods as 0-RTT early data, but the method alone does not prevent duplicates: clients and proxies can retry requests, and users can double-submit. Important mutations still need transactions, uniqueness constraints, or idempotency keys.

DTO Separation

We split transport types by application context. A card view should expose only what the page needs:

type CatalogCard struct {
    ID        uint
    Title     string
    Slug      string
    Price     string
    Currency  string
    Image     string
}

The repository also uses an explicit projection for list queries instead of loading large text and JSONB columns. This reduces transferred and decoded data, although the actual gain must be measured against the real query and dataset rather than assumed.

What This Architecture Helps Prevent

Accidental side effects on safe routes — GET stays safe under replay, crawling, and prefetching
Scattered business rules — mutations have one service-level entry point
Over-fetching — explicit repository projections make selected columns reviewable
Transport/storage coupling — HTTP types do not have to mirror database models

It is more boilerplate than a flat handler-does-everything approach. The rule is worth it because it makes behavior easier to test and reason about. It is not, by itself, complete replay protection: mutation endpoints still require their own idempotency and authorization controls.

This article is based on lessons from building Towami, a multi-country marketplace and white-label storefront platform. Follow for more practical notes on Go, HTMX, infrastructure, and SaaS.

Serving Tenant Storefronts on Custom Domains with Go + Cloudflare for SaaS

Anton Makasin — Sun, 04 Oct 2026 06:00:00 +0000

A merchant storefront can live on a platform subdomain (mystore.platform.example) or a custom domain (www.store.example). Both options are served by the same Go application. Here is how we resolve which shop to render.

The Shop Host Middleware

When a request hits the shops binary, a middleware extracts the Host header and figures out which shop it belongs to:

func (m *ShopHostMiddleware) Resolve() gin.HandlerFunc {
    return func(c *gin.Context) {
        host := requestHost(c.Request)
        if host == "" || m.isApexHost(host) {
            c.Next()
            return
        }
        if slug, ok := m.subdomainSlug(host); ok {
            if _, isCountry := helper.Countries[slug]; isCountry {
                c.AbortWithStatus(http.StatusNotFound)
                return
            }
        }
        shop, err := m.resolveShop(c.Request.Context(), host)
        if err != nil {
            c.AbortWithStatus(http.StatusInternalServerError)
            return
        }
        if shop == nil {
            if m.isShopSubdomain(host) {
                c.AbortWithStatus(http.StatusNotFound)
                return
            }
            c.Next() // not a configured custom hostname
            return
        }
        c.Set(ShopContextKey, shop)
        c.Next()
    }
}

resolveShop tries two strategies:

Subdomain lookup: extracts mystore from mystore.platform.example and looks up that unique slug.
Custom-domain lookup: normalizes the supported www.store.example hostname to the stored root, store.example, and looks it up through a unique index.

Country subdomains are explicitly excluded because they belong to the marketplace application. We parse hostnames with net.SplitHostPort, lowercase them, and validate them against known suffixes. If a reverse proxy supplies X-Forwarded-Host, trust it only from a proxy you control.

Cloudflare for SaaS: The SSL Part

The hardest part of custom domains is not routing but certificate issuance and renewal. We use Cloudflare for SaaS custom hostnames for that lifecycle.

The setup:

We configure a fallback origin such as connect.platform.example
When a merchant adds a custom domain, our app calls the Cloudflare API to create a Custom Hostname
The merchant sets CNAME www → connect.platform.example at their DNS provider

Our Custom Hostname request uses HTTP DCV. Once the www CNAME routes through Cloudflare, Cloudflare can validate the hostname and issue the certificate for www.store.example. Cloudflare retries failed validation on a backoff schedule. A status GET only observes that process; if we need an immediate recheck after DNS is fixed, the documented API flow is to PATCH the hostname with its current SSL settings.

Why www-Only

We only support www.{domain}, not bare apex domains. A conventional CNAME cannot coexist with the other records required at a DNS zone apex. Some DNS providers offer ALIAS/ANAME or CNAME flattening, but support and behavior vary. The merchant therefore configures an HTTP redirect from store.example to www.store.example with their DNS or registrar provider.

This is a product constraint, not a universal Cloudflare limitation. Cloudflare for SaaS also documents apex proxying, but its prerequisites and plan availability should be checked before committing to it.

Status Tracking

For each shop we store:

the provider's opaque Custom Hostname ID
a local status: pending, active, or error
a provider status or error summary

When a merchant connects a domain, we create or find the Cloudflare hostname, store its ID, and map Cloudflare's hostname and SSL states to our smaller status set. The dashboard can explicitly refresh that state. A scheduled poller is another option, but the current implementation does not depend on one.

The API token stays server-side and is never returned to the browser; production credentials should have only the required zone permissions. Provider error text is untrusted. Our templates HTML-escape it, but a stronger boundary is to log detailed provider errors server-side and show merchants a bounded, generic message.

What We Learned

Define one canonical hostname. In our case, input may include www., but storage uses the root and serving uses www.. This rule must be consistent in validation, provisioning, and lookup.
Use reserved example domains in documentation. A wildcard under a local .test domain is enough to exercise host routing without Cloudflare.
Index both lookup keys. Host resolution is on the request path, so subdomain slugs and custom domains need unique indexes. Add caching only with an explicit invalidation strategy.
Make provisioning idempotent. Before creating a hostname, look it up; retries should not produce duplicate provider resources.

Custom domains are table stakes for many SaaS storefront products. Cloudflare for SaaS made it possible without running our own ACME client or certificate renewal infrastructure.

This article is based on lessons from building Towami, a multi-country marketplace and white-label storefront platform. Follow for more practical notes on Go, HTMX, infrastructure, and SaaS.

Multi-Host Routing in Go: One Binary, Many Domains

Anton Makasin — Tue, 29 Sep 2026 06:00:00 +0000

Our marketplace is organized around multiple country sites. Each country gets its own subdomain, while the apex is the cross-country portal. A single Go application serves the portal and country catalogs.

The Middleware Approach

Instead of path-based routing (/cr/en/vehicles), we use host-based resolution. A Gin middleware extracts the country from the Host header before any route handler fires:

func CountryHostMiddleware(cfg *config.Config) gin.HandlerFunc {
    return func(c *gin.Context) {
        if slug, ok := helper.CountrySlugFromHost(c.Request.Host, cfg); ok {
            c.Set(string(CountryContextKey), slug)
            c.Set(OnCountryHostContextKey, true)
        }
        c.Next()
    }
}

CountrySlugFromHost strips the port, lowercases the host, and accepts only a one-label subdomain in the country allowlist. If cr.example.com comes in, the context gets country=cr. Edge routing sends shop hosts to a different application; this middleware must not treat an arbitrary subdomain as a country.

A later locale middleware derives language preferences and puts both country and language into the request context. Currency is resolved separately because a visitor may choose a display currency that differs from the country's default.

URL Structure: Language in Path, Country in Host

Each country host serves localized URLs such as /{lang}/vehicles and /{lang}/real-estate. The host's default-language homepage lives at /; requesting the redundant default-language homepage returns a 301 to /.

This design gives us clean hreflang tags for Google:

<link rel="alternate" hreflang="en-CR" href="https://cr.example.com/en/vehicles" />
<link rel="alternate" hreflang="es-CR" href="https://cr.example.com/es/vehiculos" />
<link rel="alternate" hreflang="x-default" href="https://cr.example.com/es/vehiculos" />

The Cookie Problem

Authentication is shared across the platform's apex and country subdomains. The session cookie uses Domain=example.com, so the browser sends it to both example.com and its subdomains. A leading dot is accepted by browsers but ignored by modern cookie semantics, so Domain=.example.com does not create a different scope.

That scope is also a security boundary. A compromised sibling subdomain may be able to shadow or overwrite a domain cookie, and SameSite does not isolate sibling subdomains because they are the same site. We therefore share the cookie only with trusted platform hosts and set Secure, HttpOnly, and an appropriate SameSite value. Tenant-owned custom domains cannot share this cookie.

If cross-subdomain login is unnecessary, a host-only cookie is safer and can use the __Host- prefix. That prefix is incompatible with a Domain attribute.

Legacy URL Migration

We originally had country paths on the apex: example.com/cr/en/vehicles. When we moved to subdomains, we needed 301 redirects:

func LegacyCountryRedirectMiddleware(cfg *config.Config) gin.HandlerFunc {
    return func(c *gin.Context) {
        if helper.OnCountryHost(c, cfg) {
            c.Next()
            return
        }
        if target := helper.LegacyCountryPathRedirect(
            c.Request.URL.Path, c.Request.URL.RawQuery, cfg,
        ); target != "" {
            c.Redirect(http.StatusMovedPermanently, target)
            c.Abort()
            return
        }
        c.Next()
    }
}

Old links such as example.com/cr/en/vehicles now redirect permanently to cr.example.com/en/vehicles. We also preserve the query string deliberately and test malformed country/language combinations so the redirect cannot become an open redirect.

The Result

One binary and one router serve the portal and multiple country catalogs. Adding a country still requires registry, locale, currency, SEO, and data changes, but it does not require a new service architecture.

This article is based on lessons from building Towami, a multi-country marketplace and white-label storefront platform. Follow for more practical notes on Go, HTMX, infrastructure, and SaaS.

How We Run 4 Services From One Go Monorepo

Anton Makasin — Thu, 24 Sep 2026 21:21:09 +0000

We're building Towami — a commerce platform that combines white-label online stores with country marketplaces. One codebase produces four long-running services, each with a separate entry point and responsibility.

The Four Binaries

cmd/
├── site/     → marketplace portal + country catalogs
├── shops/    → merchant storefronts on custom domains
├── admin/    → back-office panel
└── worker/   → background jobs via Asynq (no HTTP)

site serves the main domain and multiple country subdomains. shops serves merchant storefronts on platform subdomains and custom domains. admin is the back-office dashboard. worker processes email, Telegram, and import tasks through Redis queues.

The repository also has an importer command. It is a CLI utility rather than a long-running service, so it is outside the four in the title.

Shared `internal/` With Clean Boundaries

All four binaries import from a single internal/ package tree:

router → middleware → handler → service → repository → model/DB
                        ↘ templates (Templ)
                        ↘ dto

The key is sub-packaging by application: handler/site/, handler/shops/, and handler/admin/, with the same split for services, repositories, DTOs, and templates. Each binary imports only the packages it needs. The worker, for example, does not import HTTP handlers or templates.

Go's internal directory also prevents code outside the parent module tree from importing these packages. It does not enforce our layer order, though; that remains an architectural convention backed by review and tests.

Why Not Microservices?

Early on, we considered splitting into separate repos. Three things stopped us:

Shared models. Products, shops, and users are the same entities everywhere. Duplicating model definitions across repos means sync hell.

Atomic refactors. When we change a database column, the handler, service, repository, DTO, and template all update in one commit.

Deployment simplicity. Four builds with CGO_ENABLED=0 produce self-contained binaries that can be managed as independent service units. We do not need container orchestration, a service mesh, or versioned APIs between these cooperating applications.

This is still a modular monolith: the binaries share code and data contracts. Separate executables alone do not make them microservices.

The Gotcha: Air and Hot Reload

In development, each service runs in Docker with Air for hot reload. Without scoped watch rules, an edit to shared code can rebuild every service.

We solved this with scoped watch configs. The worker Air config ignores templates/, handler/, and router/. The admin config ignores handler/site/ and handler/shops/. Each service only rebuilds when files relevant to it change.

# Worker: exclude HTTP and UI layers
[build]
  exclude_dir = [
    "internal/templates",
    "internal/handler",
    "internal/router",
    "assets",
    "storage",
  ]

Bottom Line

A Go monorepo with one cmd/ entry point per service gives us process-level separation while keeping atomic refactors and one go.mod. It is a good fit while the applications share a schema and are maintained by one team. If independent ownership or deployment becomes the real constraint, the boundary can change later.

Next up: how one of those binaries serves multiple country sites on different subdomains with a single process.

This article is based on lessons from building Towami, a multi-country marketplace and white-label storefront platform. Follow for more practical notes on Go, HTMX, infrastructure, and SaaS.

DEV Community: Anton Makasin

Mobile-First SCSS Architecture with Dart Sass in Docker

The Directory Structure

Why This Matters

Building Inside Docker

Compiled Output

The Gotcha: Air Doesn't Watch SCSS

What We'd Change

HTMX + Alpine.js: Building a SPA Feel Without a Client-Rendered App

The Principle

HTMX Navigation: Catalog Example

Alpine.js: Client-Side State

Notifications via HTMX Triggers

Why This Stack?

Why We Chose Templ Over html/template (and What We Learned)

The Problem With html/template

What Templ Gives Us

The Generation Step

Multi-Container Deduplication

What We Learned

Targeting 100/100 PageSpeed: Our Critical CSS Inlining Strategy

The Problem With One Big CSS File

Our Three-Tier CSS Strategy

1. Inlined Route CSS

2. File-Linked CSS (account pages)

3. Lazy-Loaded Bundles (everything else)

Mobile-First File Structure

The Templ Integration

The Results

Background Jobs in Go with Asynq: Emails, Notifications, and Resilience

Why Separate the Worker

Task Architecture

What Lives in the Worker

The Dev Gotcha

Retry Policy

Why Not Just goroutines?

Our Layered REST Architecture in Go: Why GET Must Not Mutate Application State

The 0-RTT Replay Problem

Our Layered Approach

Practical Enforcement

DTO Separation

What This Architecture Helps Prevent

Serving Tenant Storefronts on Custom Domains with Go + Cloudflare for SaaS

The Shop Host Middleware

Cloudflare for SaaS: The SSL Part

Why www-Only

Status Tracking

What We Learned

Multi-Host Routing in Go: One Binary, Many Domains

The Middleware Approach

URL Structure: Language in Path, Country in Host

The Cookie Problem

Legacy URL Migration

The Result

How We Run 4 Services From One Go Monorepo

The Four Binaries

Shared internal/ With Clean Boundaries

Why Not Microservices?

The Gotcha: Air and Hot Reload

Bottom Line

Shared `internal/` With Clean Boundaries