DEV Community: vavilov2212

Deploying a headless commerce app: a Next.js storefront on Vercel and a Keystone GraphQL admin on Google Cloud Run

vavilov2212 — Tue, 21 Jul 2026 00:21:33 +0000

TL;DR

A digital goods store deployed as three decoupled services around one database: a Next.js storefront, a Keystone 6 admin with a GraphQL API served by Apollo Server, and Postgres. They run on Vercel, Google Cloud Run, and Neon, and because each service is on a managed free tier, the demo costs nothing to run.

Code: https://github.com/vavilov2212/digital-products-shop
Live shop: https://digital-products-shop.vercel.app
Roadmap: connect a real product supplier API, then build the payment flow.

The rest of this article is the architecture and the full deployment, one host at a time.

The architecture, split into three services
What Keystone actually is
Service 1: the storefront (Next.js on Vercel)
Service 2: the admin and GraphQL API (Keystone 6 on Google Cloud Run)
Service 3: the database (Postgres on Neon)
Local development with Docker Compose
The production container (multi-stage Docker build)
CI/CD with GitHub Actions
How a request is served, and what a deploy does
Standing it up from scratch
Environment variables
Locking down the public GraphQL endpoint
Takeaways

I built a small store for digital goods and put it into production on three managed free tiers. The interesting part is not the shop itself. It is how the pieces are split into independent services and wired together so each one can scale, sleep, and deploy on its own.

The stack:

Next.js 13 (App Router) for the storefront
Keystone 6 for the admin panel and a public GraphQL API
Postgres for storage
Docker for the containers and Docker Compose for local development
GitHub Actions for CI/CD

Hosted on Vercel, Google Cloud Run, and Neon.

The architecture, split into three services

The system is three services with one shared database. Each service has one job.

                           a user
                             |
                             v
        +--------------------------------------------+
        |  Vercel  -  storefront (Next.js, ISR)      |
        |  static pages, revalidate at most once/day |
        +--------------------------------------------+
                             |
              queries Postgres directly, through an
              embedded Keystone/Prisma context
              (never calls the admin service)
                             |
                             v
        +--------------------------------------------+
        |  Neon  -  Postgres (serverless)            |
        |  single source of truth                    |
        +--------------------------------------------+
                             ^
             admin writes + Prisma migrations
                             |
        +--------------------------------------------+
        |  Google Cloud Run  -  Keystone admin       |
        |  + public GraphQL API, scale to zero       |
        +--------------------------------------------+

💡 The load-bearing decision. The storefront reads Postgres directly
through Keystone's embedded context and never calls the admin service. That one
choice is what makes the free-tier setup work: the admin service is allowed to
scale to zero and sleep, and its cold starts never touch a user request.

What Keystone actually is

Before the service breakdown, it helps to know what Keystone is under the hood, because it is doing more than one job. Keystone is a bundle of tools you would otherwise wire up yourself, all generated from a single schema:

Prisma as the ORM and migration engine
Apollo Server for the GraphQL API (configured right in keystone.ts via apolloConfig)
A generated Admin UI built on React and Next.js
Session and access-control primitives

You could assemble these separately, a Prisma schema plus a hand-written Apollo Server plus your own admin pages, and some teams do. Keystone's pitch is that it generates all of it from one list schema so you do not have to.

Keystone can also run in two shapes, and this project uses both:

Standalone: Keystone runs its own server for the Admin UI and the GraphQL endpoint. That is what runs on Cloud Run here.
Embedded: Keystone's data layer is imported into another Node or Next.js process through getContext, so you can run Keystone queries in-process without going through the GraphQL server over the network.

The storefront uses the embedded shape to read Postgres directly, while the Admin UI and the Apollo GraphQL server run standalone on Cloud Run. That split is the whole trick, and the next three sections walk through each piece.

Service 1: the storefront (Next.js on Vercel)

The storefront is a Next.js 13 App Router app on Vercel. The product, category, and cart pages are rendered with ISR, which stands for Incremental Static Regeneration. Each page is built once into static HTML and then allowed to rebuild itself on a schedule, so it stays fast to serve and does not go stale forever. The schedule here is revalidate: 86400, so 24 hours at most.

The important detail is how the storefront gets its data. It does not call the Keystone GraphQL server over the network. It imports Keystone's embedded context and runs queries against Postgres in-process. The whole product fetch is a direct database query with no external call:

export async function getProducts() {
  return await keystoneContext.sudo().query.Product.findMany({
    orderBy: { productId: 'asc' },
    query: `id productId label description price imageUrl currency { id code name }`,
  });
}

Because this runs at build time and during background revalidation, the data in the live pages is a snapshot from the moment of the last build. That fact matters during a deploy.

Why Vercel: it runs Next.js with almost no configuration, the CDN and ISR caching are built in, and it redeploys on every push to master through its GitHub integration.

Service 2: the admin and GraphQL API (Keystone 6 on Google Cloud Run)

Keystone 6 gives me two things from one schema: an admin UI for editing products, and a GraphQL API. GraphQL is a query language where the client asks for exactly the fields it wants in one request. In this project the GraphQL playground and schema introspection are intentionally left public, so the API is browsable as part of the demo.

Keystone runs as a Docker container on
Google Cloud Run. Cloud Run is Google's
serverless container platform: you hand it an image and it runs it, scaling the number of instances up and down with traffic, including down to zero. Scale to zero means that when nobody is using the admin, Cloud Run stops the container and charges nothing. The first request after an idle period pays a cold start, a couple of seconds here while the container boots.

That cold start would be unacceptable if users depended on this service. They do not, because the storefront reads Postgres directly. Only I use the admin, so a two-second wake-up on login is fine.

Two things run on every container boot:

Prisma migrations (prisma migrate deploy), which apply any pending versioned schema changes so the database shape matches the code.
An onConnect hook that optionally seeds demo data, gated behind a SEED_ON_STARTUP environment variable.

onConnect: async context => {
  if (process.env.SEED_ON_STARTUP === 'true') {
    await seedDemoData(context);
  }
},

The service is named keystone-admin in the us-central1 region, pinned to a maximum of one instance so migrations never run concurrently.

Why Cloud Run: it runs any container, it only bills while the container is awake, scale to zero costs nothing at rest, and it deploys from a GitHub Action on every push to master.

Service 3: the database (Postgres on Neon)

Neon is serverless Postgres.
It is the single source of truth for products, categories, currencies, carts, and orders. Both other services talk to it.

Neon also suspends the compute after about five minutes of no queries and resumes in roughly half a second to two seconds on the next query. For a demo this is invisible almost all the time.

Neon hands you two connection strings, and matching the right one to the right service is load-bearing.

💡 Pooled vs direct, and where each string goes.
The pooled string (its host contains -pooler) routes through
PgBouncer, which lets many short-lived requests
share a small set of real database connections. It goes to the storefront on
Vercel, with ?sslmode=require&pgbouncer=true&connect_timeout=15 appended,
because the storefront opens many short connections.
The direct string goes to Cloud Run, because
Prisma migrations do not work through the pooler
and Keystone runs migrations on boot. Swap the two and migrations fail on boot
in confusing ways.

Why Neon: real Postgres, a genuine free tier (0.5 GB storage, 100 compute-hours a month), and fast enough resume that the suspend does not hurt.

Local development with Docker Compose

Production is three separate hosts, but locally the whole thing comes up with one command through Docker Compose. Docker Compose runs a set of containers defined in one YAML file. docker-compose.dev.yml defines three services that mirror production:

services:
  nextjs-front:      # Next.js storefront on :3000, ./src and ./public mounted for hot reload
  keystone-server:   # Keystone admin + GraphQL on :4000, SEED_ON_STARTUP=true
  db:                # postgres:latest on :5432, data in ./.dbdata

Bring it all up:

docker compose -f docker-compose.dev.yml up -d
# storefront: http://localhost:3000
# admin:      http://localhost:4000
# postgres:   localhost:5432

Two details make the dev loop pleasant:

The storefront container mounts ./src and ./public as volumes, so front-end edits hot-reload without a rebuild.
The Keystone service sets SEED_ON_STARTUP=true, so a fresh database is populated with the demo catalog on first boot.

The local Postgres uses POSTGRES_HOST_AUTH_METHOD: trust because it is never exposed outside the compose network.

The production container (multi-stage Docker build)

The Keystone image is a multi-stage Docker build. Multi-stage means the build runs in phases and only the final phase ships, so build-time tooling does not bloat the runtime image. The stages here are base, deps, builder, and runner:

FROM node:20-slim AS base       # Debian slim, openssl installed
FROM base AS deps               # npm ci --legacy-peer-deps
FROM base AS builder            # npm run keystone:build
FROM base AS runner             # CMD ["npm", "run", "keystone:start"]

One line in that Dockerfile is a scar from a real bug.

⚠️ Use the Debian (slim) base, not Alpine.
Prisma's Alpine (musl) query engine links against OpenSSL 1.1 and segfaults
inside Node 20, which ships OpenSSL 3, during TLS handshakes. A TLS handshake
happens on every sslmode=require connection, which is exactly what Neon
requires. So an Alpine image builds fine and then crashes the moment it tries
to reach the database. node:20-slim is Debian and ships OpenSSL 3 engines,
which fixes it. This cost real debugging time and is not something you would
guess from the error.

One more Cloud Run detail lives in this image: PORT is deliberately not set.
Keystone reads process.env.PORT at runtime, and Cloud Run injects PORT=8080.
Letting the platform pick the port is part of the
Cloud Run container contract.

CI/CD with GitHub Actions

Two GitHub Actions workflows drive continuous integration and deployment.

ci.yml runs on pull requests and on pushes to dev. It generates the Keystone and Prisma types without a database (keystone postinstall), type-checks with tsc, and runs the linter. The lint step is allowed to fail without blocking, because the repo carries some known stylistic debt. This workflow does not deploy.

deploy-keystone.yml runs on pushes to master. It builds the Keystone
container, pushes it to Artifact Registry (Google's container image store), and deploys it to Cloud Run:

on:
  push:
    branches: [master]
steps:
  - uses: google-github-actions/auth@v2
    with:
      credentials_json: ${{ secrets.GCP_SA_KEY }}
  - run: docker build -f docker/production/Dockerfile.keystone -t "$IMAGE:${{ github.sha }}" .
  - run: docker push "$IMAGE:${{ github.sha }}"
  - run: gcloud run deploy keystone-admin --image "$IMAGE:${{ github.sha }}" --region us-central1 ...

Runtime environment variables are set once on the Cloud Run service and preserved across deploys, so the workflow never has to know any secrets beyond the two it needs to authenticate: GCP_PROJECT_ID and GCP_SA_KEY.

How a request is served, and what a deploy does

Two flows tie the services together.

A user request:

The user asks Vercel for a page.
Vercel serves the pre-built static HTML instantly.
If the page is past its 24-hour window, Vercel rebuilds it in the background on the next request, querying Neon directly.

Cloud Run never appears in that path. That is the whole point.

A deploy, triggered by one push to master:

   git push origin dev:master
             |
      +------+------------------------+
      |                               |
      v                               v
   Vercel rebuilds                GitHub Action
   the storefront                 deploy-keystone.yml
   (queries Neon, bakes           builds + deploys the
   current data into pages)       Keystone container to Cloud Run

Production is the master branch. Work happens on dev, which is not
production. The two deploys run independently and do not finish at the same time, so a fresh storefront build can briefly ship with data that is about to change underneath it.

Getting work onto master is a fast-forward push. A fast-forward is the clean git case where master is simply behind dev with no divergent history, so it slides forward with nothing to merge:

git fetch origin
git merge-base --is-ancestor origin/master dev && echo yes   # prints yes if safe
git push origin dev            # update remote dev
git push origin dev:master     # fast-forward master to dev

You can watch the Cloud Run deploy from the terminal:

gh run list --branch master --workflow "Deploy Keystone to Cloud Run" --limit 3
gh run watch <run-id> --exit-status

Standing it up from scratch

Everything you need to reproduce the deployment, one host at a time.

Neon

Create a free project at neon.tech, in an AWS region near Cloud Run and Vercel (us-east or us-central).
Copy both connection strings from the dashboard. The direct one (...@ep-xxx.region.aws.neon.tech/neondb?sslmode=require) goes to Cloud Run. The pooled one (its host contains -pooler) goes to Vercel, with Prisma params appended: ?sslmode=require&pgbouncer=true&connect_timeout=15.

Google Cloud Run

Billing must be linked, though usage stays inside the always-free tier at demo traffic. Every command below also runs from Cloud Shell in the browser, which comes pre-authenticated, so no local CLI is required.

gcloud projects create <PROJECT_ID> && gcloud config set project <PROJECT_ID>
gcloud services enable run.googleapis.com artifactregistry.googleapis.com
gcloud artifacts repositories create shop --repository-format=docker --location=us-central1

First deploy, which seeds the catalog because SEED_ON_STARTUP=true is set:

gcloud auth configure-docker us-central1-docker.pkg.dev
docker build -f docker/production/Dockerfile.keystone \
  -t us-central1-docker.pkg.dev/<PROJECT_ID>/shop/keystone:initial .
docker push us-central1-docker.pkg.dev/<PROJECT_ID>/shop/keystone:initial

gcloud run deploy keystone-admin \
  --image us-central1-docker.pkg.dev/<PROJECT_ID>/shop/keystone:initial \
  --region us-central1 --min-instances 0 --max-instances 1 \
  --memory 512Mi --cpu 1 --allow-unauthenticated \
  --set-env-vars "DATABASE_URL=<NEON_DIRECT_URL>,SESSION_SECRET=<openssl rand -hex 32>,STORAGE_KIND=local,PRISMA_SCHEMA_DISABLE_ADVISORY_LOCK=true,SEED_ON_STARTUP=true,KEYSTONE_PUBLIC_URL=<filled after first deploy>"

Right after the first deploy, confirm the catalog exists, then remove the seed flag and set the real public URL:

gcloud run services update keystone-admin --region us-central1 \
  --remove-env-vars SEED_ON_STARTUP \
  --update-env-vars KEYSTONE_PUBLIC_URL=https://<service-url>

Then set a $1 budget alert in Billing so any accidental spend pings you early.

⚠️ Close the initFirstItem window immediately. Keystone lets anyone create
the first admin user while the User table is empty. Open the service URL and
create yours right after the first deploy, so nobody else can.

Note: the container filesystem is ephemeral, so admin-uploaded images
(STORAGE_KIND=local) disappear on the next cold start. The catalog itself lives in Neon and in repo-shipped static images, so it is unaffected. Wire S3 or R2 and STORAGE_KIND=s3 if uploads ever need to persist.

Vercel

Import the GitHub repo at vercel.com/new with the Next.js preset.
Override the build command to npx keystone postinstall && next build. The first half generates the Keystone and Prisma types without a database; the second half prerenders the pages, which does query Neon, so the pooled DATABASE_URL must be present at build time.
Set the environment variables (next section).
Vercel then deploys on every push through its GitHub integration.

GitHub Actions secrets

Create a deploy service account, grant it the three roles the workflow needs, and export a key:

gcloud iam service-accounts create github-deploy
for role in run.admin artifactregistry.writer iam.serviceAccountUser; do
  gcloud projects add-iam-policy-binding <PROJECT_ID> \
    --member serviceAccount:github-deploy@<PROJECT_ID>.iam.gserviceaccount.com \
    --role roles/$role
done
gcloud iam service-accounts keys create key.json \
  --iam-account github-deploy@<PROJECT_ID>.iam.gserviceaccount.com

Add GCP_PROJECT_ID (the project id) and GCP_SA_KEY (the contents of
key.json) as repository secrets, then delete the local key file.

Environment variables

Set in three places, and some values must match across them.

Variable	Vercel	Cloud Run	Local	Notes
`DATABASE_URL`	pooled	direct	optional	pooled for the storefront, direct for migrations
`DB_*` (name/user/password/host/port)	-	-	yes	dev docker fallback when no `DATABASE_URL`
`SESSION_SECRET`	yes	yes	optional	same value on both hosts (`openssl rand -hex 32`)
`REVALIDATE_SECRET`	yes	-	optional	guards `/api/revalidate` and `/api/sync-supplier`
`KEYSTONE_PUBLIC_URL`	-	yes	-	public base URL for Keystone-served images
`PRISMA_SCHEMA_DISABLE_ADVISORY_LOCK`	-	`true`	-	needed for Neon migrations on boot
`SEED_ON_STARTUP`	-	temporary	`true` (dev)	flip on to seed, then remove
`STORAGE_KIND`	`local`	`local`	`local`	`local` or `s3` for admin uploads

The pair that trips people up is DATABASE_URL: pooled on Vercel, direct on Cloud Run.

⚠️ SESSION_SECRET must be identical on Vercel and Cloud Run. The Vercel
build imports the auth code that reads it, so a mismatch breaks the build, not
just runtime sessions.

Locking down the public GraphQL endpoint

The Keystone GraphQL API on Cloud Run is reachable from the public internet. That raises two separate questions: who is allowed to read the data, and who is allowed to hit the endpoint at all. I handled the first one in code. The second one has a range of options, and I stopped at the point that is enough for a demo.

What I did: access control in the schema

Keystone has a per-list access control API, and I used it to session-gate everything that holds personal data:

User, Order, Cart, and CartProduct now require an admin session for every query and mutation. An anonymous caller on the public endpoint can no longer read customer emails, enumerate users, or forge and delete orders.
Product, Category, and Currency stay publicly queryable, because they are the read-only catalog and hold no personal data. Their writes are admin-only.

I also disabled the GraphQL playground and schema introspection in production. In local development Keystone serves a playground and lets you introspect the schema, which is convenient. In production both are off, so the endpoint does not advertise its shape to strangers.

None of this touched the storefront. It reads and writes through the in-process Keystone context, which runs as an admin and bypasses access control, so tightening the public endpoint changed nothing for users.

💡 Access control is the real lock, not CORS or a hidden playground.
Turning off the playground and introspection is defense-in-depth: it stops the
endpoint from advertising its schema, but a determined caller with curl does
not need the schema to start guessing. What actually protects the data is
per-list access control. CORS only restricts cross-origin JavaScript in a
browser and does nothing to a bot or a script.

Going further: taking the endpoint off the public internet

For a demo, the access control above is enough, and I stopped there. If this took real traffic, or if bots hammering /api/graphql became a nuisance, the next step is to stop anonymous requests from reaching the service at all. Because the storefront never calls Cloud Run over HTTP, the whole service can be made private without breaking anything. The options run from free to paid:

Cloud Run IAM auth plus an authenticated proxy (free). Make the service private with --no-allow-unauthenticated, and anonymous traffic is rejected at the ingress before a container even starts, so bot spam costs no instance time. To use the admin you open a local proxy signed in as your Google account. The trade-off is that there is no public, bookmarkable admin URL.
A load balancer with IAP or Cloud Armor (paid). A load balancer is a managed entry point that receives all traffic and forwards it to the service, and on GCP it is also where the two features below attach. It has no free tier, so this route starts around $18 a month whether or not anyone visits.
- Identity-Aware Proxy (IAP) puts a Google sign-in gate in front of a public URL, so only identities you allow can reach the app. This is the choice if you want a public admin URL protected by login.
- Cloud Armor is Google's web application firewall (WAF) and rate-limiting layer. You can allow only your own IP, or throttle requests per IP, for example 60 a minute, so a bot hammering /api/graphql gets rejected with a 429. This is the direct answer to endpoint spam.

Option	What it does	Rough cost
Cloud Run IAM + local proxy	Rejects all anonymous traffic at the ingress; admin via an authenticated proxy	$0
IAP	Google sign-in gate in front of a public admin URL	~$18/mo (the load balancer)
Cloud Armor	WAF and per-IP rate limiting on the endpoint	~$18/mo + policy and per-request fees

For now the endpoint stays publicly reachable, the data is protected by the access control in the schema, --max-instances 1 bounds the cost of any abuse, and the $1 budget alert would surface it. That is a deliberate stopping point, not an oversight.

Takeaways

The whole thing rests on one architectural decision: the storefront reads the database directly through Keystone's embedded context instead of calling the admin service. That decoupling is what lets the admin scale to zero, lets each service deploy on its own, and keeps the bill at zero for a demo.

Everything else follows from taking that separation seriously:

the multi-stage Docker build and the Debian base that keeps Prisma alive on TLS
the pooled versus direct Neon connection strings
the seed-on-boot hook gated behind an environment variable
the CI/CD split between dev and master

If you want to poke at it:

Code: https://github.com/vavilov2212/digital-products-shop
Live shop: https://digital-products-shop.vercel.app

Run -> Log -> Distill: a self-improving memory for AI-assisted development

vavilov2212 — Sun, 12 Jul 2026 16:38:08 +0000

Every AI coding session starts with amnesia.

Yesterday the agent spent two hours hunting down a state-sharing bug. Today it will happily reintroduce that same bug, in the same codebase, with the same confidence. The context window closed, and everything the agent learned went with it.

I'm building a full-stack GraphQL store (Next.js + Keystone 6 + PostgreSQL, dissected in the rest of this series) almost entirely through AI-assisted sessions in Claude Code. A few sessions in, I got tired of the amnesia and changed the workflow itself. I now run every task with Run → Log → Distill, built from these ideas:

while the agent works, it appends to a WAL (a write-ahead log: the work journal);
when the work is done, a compaction step melts that log into a post-mortem: a small file of rules that every future session must read before writing code.

This pattern is being reinvented all over the industry right now. The tools are shipping it as a native feature: Claude Code auto memory, Cursor Memories, Devin's Cascade Memories. Agents that write reflections on their own failures and reread them on the next attempt are described here: Reflexion or here compounding engineering.

The pattern described in this article moves with you between tools, works today in any of them, and nothing enters long-term memory without your review. More links in prior art at the end.

Below are three prompts you can copy as-is.

Chat history is not knowledge
Two kinds of memory: a WAL and a post-mortem
The lifecycle at a glance
Case 1: a planned refactor
- Prompt 1: execute the plan
- Prompt 2: compact the journal
Case 2: a spontaneous session
- Prompt 3: distill a spontaneous session
The loop closes
Don't keep the journal in CLAUDE.md
Limitations
Prior art
Steal it

Chat history is not knowledge

Most AI coding setups already have some persistent context. Claude Code reads CLAUDE.md, Cursor has rules files. In practice these hold static facts: how to run the dev server, where the tests live, what the folders mean.

The knowledge that actually matters looks different:

why a refactor was done, so the next session doesn't undo it;
which innocent-looking pattern caused a production bug, and the exact command that diagnoses it;
which corners were cut on purpose, so they get revisited instead of rediscovered.

This makes the agent write transcripts about its own work, while the context is still in the window.

Two kinds of memory: a WAL and a post-mortem

Cognitive science splits memory into episodic (what happened to me: "I burned my hand on that kettle") and semantic (what I know: "kettles are hot"). A brain constantly converts the first into the second. CoALA - Cognitive Architectures for Language Agents.

The WAL. Before a database touches its real data structures, it appends the intended change to a write-ahead log. Appending to the end of a file is the fastest, safest thing a disk can do. If the process crashes mid-write, the log replays and nothing is lost. PostgreSQL calls it WAL literally (pg_wal), MySQL calls it the redo log, SQLite has a WAL mode. The price is that a WAL is write-optimized and read-terrible: it's a chronological dump, and finding the current state of anything means replaying history.

Our work journal is a WAL: an append-only file the agent writes during execution, cheap and raw, full of detail nobody will ever reread in full.

Compaction. Log-structured engines (RocksDB, Cassandra) periodically merge their raw files: overwritten values get dropped, duplicates collapse, and what remains is small and fast to read. Kafka literally calls its variant "log compaction". Our distillation step is compaction: the raw journal (or the raw session) gets melted into current rules, and the journal is archived.

The compacted store. Here it's a file named POST_MORTEM.md, in honor of the SRE practice of blameless incident post-mortems. Purists will note that a classic post-mortem covers one incident, while this file is cumulative, more like the project's case law. Same spirit though: root causes, repair guides, action items, no blame. It holds four kinds of records: architectural decisions with their why, numbered Production Guardrails, pitfalls with repair guides, and a ledger of consciously deferred tech debt.

Databases	This workflow
WAL: fast append during work, raw, chronological	`docs/worklog/<date>-<plan>.md`, written as the agent works
Compaction: merge the log into a compact, read-optimized store	Distillation prompt at the end of a plan or session
The compacted store, what readers actually query	`POST_MORTEM.md`: guardrails, pitfalls, tech debt
Old log segments deleted after compaction	Journal archived; git keeps the history

One more file ties the loop together. The agent's auto-loaded entry point (CLAUDE.md for Claude Code) stays thin: project description, commands, and one hard pointer as its first line:

👉 IMPORTANT: Before writing any new code, adding features, or refactoring, you MUST first read POST_MORTEM.md and strictly follow the architectural rules and Production Guardrails recorded there.

💡 That single line turns POST_MORTEM.md from documentation the agent might stumble upon into a precondition for writing code.

The lifecycle at a glance

Two modes, three prompts total:

	Planned work	Spontaneous work
Phase 0	Plan with a task dependency graph	(no plan; work just happens)
Phase 1: Run → Log	Prompt 1: one item at a time, WAL entry after each	the session context itself plays the role of the log
Phase 2: Distill	Prompt 2: compact the WAL into `POST_MORTEM.md`	Prompt 3: distill straight from session context

Both modes are shown below on real tasks from this store, with the prompts in full.

Case 1: a planned refactor

The best showcase of the planned mode grew out of the ugliest bug in this project's history. Every page kept its server-fetched data in a module-level store object. A module in Next.js initializes once per process, so that object was silently shared between all requests and all users. When one visitor hit an error, the error state stuck, and every visitor after them saw the error page until restart. (The full detective story is a later part of this series.)

The fix couldn't be a one-liner: introduce a per-request store provider, migrate every page and component to it, split client-only UI state into its own store, delete two dead abstractions along the way. A dozen-plus interdependent items, which is work that needs a plan.

Phase 0: a plan with a dependency graph

For planned work I don't start from a prompt at all. I use the Superpowers plugin for Claude Code, a community skill library that forces a brainstorm → design → implementation-plan pipeline before any code gets written. Any planning approach works. The output that matters for this workflow is a plan whose appendix contains a task dependency graph: which items block which, and which are independent quick wins.

That graph is what makes strictly iterative execution possible: at any moment the agent knows what one atomic, unblocked item looks like. For the refactor above, the store factory had to exist before any page could migrate to it, but the pages could migrate independently of each other.

Phase 1: run and log

Prompt 1: execute the plan

You are an autonomous AI coding agent. Your task is to execute the
attached implementation plan step by step.

So that the codebase and your memory evolve together, we will use the
practice "Run -> Log -> Distill -> Repeat". Your goal is not just to
write code, but to log the process and accumulate experience in the
work journal file `docs/worklog/<date>-<plan-name>.md`.

### RULES AND ALGORITHM:
1. Study the Appendix (the task dependency graph) at the end of the
   plan. You may not start a child task until its parents are done.
2. Work strictly iteratively: ONE specific item per ONE step. Do not
   attempt several tasks at once.
3. The algorithm for each item:
   a) [Maker] Write or change the code for the current isolated task.
   b) [Verifier] Run <verify command> and confirm nothing is broken.
   c) [Distill] Pause and append an entry to the work journal.
   d) The step is complete. Send me a short report and wait for my
      approval before moving to the next item.

### JOURNAL FORMAT:
After each completed item, append an entry to the journal, strictly
following these 5 criteria:
1. [Verified Facts] Which item is done, which files changed, which
   checks passed.
2. [What Worked] Successful patterns and approaches worth repeating.
3. [Distilled Rules] Provisional rules the next steps must respect
   (imports, dependency injection, state management).
4. [Pitfalls & What to Avoid] Compilation errors, dependency conflicts
   or bugs you hit on this item, and how you worked around them.
5. [What's Next] The next atomic task from the plan and its
   prerequisites.

Start with the first unblocked item (the quick wins, if the plan marks
them). What is your first concrete task? Describe what exactly you are
about to change in the code.

📝 Fill in: <verify command> (your test or build command: npm test, flutter test, cargo check), the journal path, and attach or reference the plan itself.

The prompt forces a rhythm: code, verify, log, report, wait. The waiting is there so that an agent drifting off course gets caught after one item instead of after ten. The logging happens right after verification, while the dead ends are still in the context window, because a diff read tomorrow won't tell you why any of it happened. And nothing enters the journal until the checks pass; that rule alone separates a work log from a chat transcript.

Here's an entry from that refactor's run (lightly reconstructed):

### Item 7: migrate category page to the per-request store
1. [Verified Facts] Item 7 done. Changed: category/[id]/page.tsx.
   `npm run typecheck` clean, smoke test green.
2. [What Worked] Same pattern as items 5-6: the page fetches data and
   passes it as initState to ProductsStoreProvider; components read
   via useProductsStore(selector).
3. [Distilled Rules] Selectors must return scalars or stable
   references. An object literal inside a selector caused an infinite
   re-render loop on item 6; don't repeat it here or on item 8.
4. [Pitfalls & What to Avoid] Keystone query results are class
   instances; passing them directly into a client component triggers
   "Only plain objects can be passed to Client Components". Wrap them
   in toPlainObject() before they cross the RSC boundary.
5. [What's Next] Item 8 (product page) was blocked by this item; now
   unblocked. Prerequisite: store factory (item 2, done).

Entries 3 and 4 are the valuable ones: a rule and a trap caught mid-run, written while the context was hot, phrased as advice for the next item. This is the raw material compaction feeds on.

Phase 2: compaction

When the last item is done, I run the second prompt.

Prompt 2: compact the journal

We have fully completed the plan! All tests pass. Our final task is a
total distillation of the experience, to capitalize it for the long
term.

Melt the work journal (docs/worklog/<date>-<plan-name>.md) down into
our architectural memory, and make sure `CLAUDE.md` remains a clean
entry point. Do not limit yourself to 5-7 bullet points: lay out every
important technical insight and rule, with no length limit.

Perform two actions, strictly in this order:

### ACTION 1: Create or extend `POST_MORTEM.md`
Record the codebase's Book of Law in the project root. Add a section
for this run, labeled with the work type ([feature] / [refactor] /
[redesign] / [deploy] / [debug] / [mixed]), and integrate its lessons
into the global sections:
1. ARCHITECTURAL CHANGES: what changed in the structure of the
   codebase and why. Justify each decision so a future session doesn't
   undo it.
2. PRODUCTION GUARDRAILS: the rules for writing code that
   crystallized out of this run (imports, state management, where
   mutable state is categorically forbidden, etc.). Phrase them as
   hard, numbered standards; justify every rule.
3. PITFALLS & TROUBLESHOOTING: every trap we hit, with a repair guide
   for each in case it recurs: symptom, root cause, the exact
   diagnostic commands.
4. FUTURE BACKLOG: a numbered ledger of deferred tech debt and areas
   needing further work.

### ACTION 2: Verify the entry point `CLAUDE.md`
Remove any temporary statuses, logs, or plan steps that leaked into
`CLAUDE.md`. It must contain ONLY:
1. A short project description.
2. Basic commands (run, test, build).
3. This hard pointer on the first line:
"👉 IMPORTANT: Before writing any new code, adding features, or
refactoring, you MUST first read POST_MORTEM.md and strictly follow
the architectural rules and Production Guardrails recorded there."

Apply the changes, archive the work journal, and show me the structure
of the resulting POST_MORTEM.md.

Compaction of that refactor's journal produced the first entries of the project's case law. Two of them:

1. It is FORBIDDEN to declare a mutable module-level object in server components / server actions. A module in Next.js initializes once per process: such an object is shared between ALL requests and ALL users. Any per-request state must be created inside the component function.

3. Server data reaches the client ONLY two ways: (a) a per-request store created by the page with its data as initState; (b) plain props. A global module-level store for server data is FORBIDDEN, as are "hydrator" components calling setState during render.

Both came out numbered and imperative, with the reasoning attached, and that formatting does real work. Agents obey "FORBIDDEN / MUST" far more reliably than "prefer / consider", and numbers make rules citable: the agent cites them in code comments, and I cite them in reviews ("this violates guardrail 3").

Case 2: a spontaneous session

Everything above assumes a plan existed. Plenty of sessions don't have one, and the best example here is the day of this store's first production deploy.

The plan looked trivial: push the admin-panel image to Google Cloud Run, run migrations against the managed Postgres (Neon), done. Instead, the container died on startup with the most generic error a platform can produce: "Container failed to start and listen on PORT=8080". No stack trace, and everything ran green locally. Three hours of digging later, the story emerged: the Alpine-based image shipped Prisma engines linked against OpenSSL 1.1, Node 20 links OpenSSL 3, and the query engine segfaulted during the TLS handshake with the production database. Local Postgres has no TLS, so no local run could have caught it. The eventual fix was one line in the Dockerfile; the three hours were spent finding that line.

No plan predicted any of this, so no journal was being kept. Sessions like this are common (the quick fix that grows into a refactor, the deploy that turns into a debugging saga), and they produce the most valuable lessons, because nothing about them was predicted.

For these sessions there's a third prompt, run once at the end.

⚠️ Prompt 3 distills from the live context window, so it has to run before the session closes. Next morning the context is gone.

Prompt 3: distill a spontaneous session

We've finished a working session in which we completed a number of
varied tasks and ad-hoc code fixes without rigid upfront planning. Now
we need to distill and capitalize this spontaneous experience following
the "Run -> Log -> Distill" principle (a self-improving system).

Your task: analyze the entire current session, the history of changed
files, and the context of the bugs we solved, then record that
experience in our architectural memory. Don't limit yourself on length;
dump every important engineering insight.

Perform two actions:

### ACTION 1: Extend/update the file `POST_MORTEM.md`
Find or create `POST_MORTEM.md` in the project root. Carefully
integrate this session's experience into it. Add a section for this
session, labeled with the work type ([feature] / [refactor] /
[redesign] / [deploy] / [debug] / [mixed]), organized into these
blocks:
1. [Architectural changes]: What exactly did we change in the
   structure of the codebase and why (which files we split, which
   dependencies we rewrote, which patterns we applied).
2. [Production Guardrails]: Which new rules for writing code, imports,
   state management, or the design system crystallized out of today's
   changes. Phrase them as hard, numbered standards that must not be
   violated.
3. [Lessons & Pitfalls]: Which non-obvious bugs, compilation errors,
   or library conflicts did we hit today? Why did they happen and how
   did we solve them? Write a detailed repair guide in case they
   recur.
4. [Residual tech debt]: What loose ends did we leave? What from
   today's work needs to be finished, refactored, or covered with
   tests in future sessions.

### ACTION 2: Refresh the entry point `CLAUDE.md`
Make sure `CLAUDE.md` in the project root is clean of process logs,
contains only current build/test commands, and has this hard pointer
on its first line:
"👉 IMPORTANT: Before writing any new code, adding features, or
refactoring, you MUST first read POST_MORTEM.md and strictly follow
the architectural rules and Production Guardrails recorded there."

Do the analysis, update the files, and give me a short summary: which
key rules and pitfalls from this session did you just commit to
memory.

It differs from Prompt 2 in three ways:

The source is the session context, not a journal. There's no WAL to compact, so the agent works from what's still in the window: the conversation, the diffs, the bugs solved.
It integrates instead of creating. Prompt 2 assumes a completed plan and writes a definitive section. Prompt 3 says "find or create" and merges carefully into whatever case law already exists.
It ends with a ranked summary. "Tell me which rules you just committed to memory" forces the agent to prioritize, and gives me a 30-second review of what just entered long-term memory. The human stays editor-in-chief. I occasionally veto a rule that over-generalizes a one-off; a self-improving system with no editor drifts into superstition.

Run at the end of the deploy saga, this prompt produced the project's most valuable pitfall entry:

3.12 "Container failed to start on PORT=8080", which was actually a segfault. Prisma's musl engines are linked against OpenSSL 1.1; node:20-alpine ships OpenSSL 3; the query engine SIGSEGVs exactly at the TLS handshake with the production database. Migrations still work (separate process!), local runs are green (local Postgres has no TLS!). Diagnosis: run the same image locally with the production DATABASE_URL and read the full stderr. Fix: node:20-slim. Lesson: "works on my machine" must include production-mode TLS.

The repair guide is deliberately a command: the next session can rerun the diagnosis in ten seconds instead of rediscovering it. A session later the lesson got generalized into guardrail 18: any image that talks TLS to a database in production gets tested against a TLS database before deploy.

The loop closes

The payoff came from a third task. Early on, the storefront called the supplier's B2B API during page rendering. One day the supplier API got flaky and took the whole storefront down with it. The distilled lesson became guardrail 4: external APIs are best-effort only, sync never sits on the render path, try { sync } catch { log }, then serve data from our own DB.

Sessions later, the agent was writing a new data-access function, and this comment appeared in the diff, unprompted:

// Pure DB read: the supplier sync is NOT called here - pages are statically
// cached (ISR), so external APIs must stay off the render path (Guardrail 4,
// tech-debt #9). Sync runs on demand via POST /api/sync-supplier.
export async function getProducts() {

The rule number, the tech-debt entry that rule closed, and the alternative chosen because of them: the agent is citing the project's own case law while writing new code. This comment did more to convince me the setup works than anything else in five sessions.

Don't keep the journal in CLAUDE.md

An early version of Prompt 1 told the agent to keep the work journal inside CLAUDE.md, the same file the agent auto-loads at the start of every session. That's also why Prompt 2 has a "clean up CLAUDE.md" action: the cleanup was a symptom of the journal living in the wrong place. The prompts above already contain the fix; the reasoning behind it:

The WAL stays out of the auto-loaded context file. Otherwise every session pays tokens for old execution logs, and the entry point gets diluted right when it should stay sharp.
One journal file per plan or session, like docs/worklog/2026-07-08-per-request-store.md. Not auto-loaded. Prompt 1 names it explicitly.
CLAUDE.md holds only commands and pointers. Mine is 48 lines: project description, how to run and verify, the hard pointer to POST_MORTEM.md.
Archive the journal after compaction. Its value has been extracted. Git keeps the raw material if you ever need it.
Tag sessions by work type: [feature], [refactor], [redesign], [deploy], [debug], [mixed] in the section header. Rules are type-agnostic (a rule born in a redesign binds a refactor just the same), but tags make future compaction of the post-mortem itself much easier.

Limitations

The post-mortem grows. Mine is ~300 lines after five sessions. At some point old session narratives need compaction of their own: keep the guardrails and pitfalls, collapse the story. Compaction is never finished, in databases or here.
Rules can over-fit. A workaround for one library version can calcify into false doctrine. The numbered format helps: rules are easy to find and repeal.
It's discipline-dependent. A good distillation pass takes a few minutes of review, and if you skip it, the knowledge from that session is simply gone.

Prior art

For digging deeper, the landscape this workflow sits in:

CoALA (Sumers et al., 2023): the paper that mapped agent memory onto the psychology terms used above (working, episodic, semantic, procedural).
ExpeL (Zhao et al., 2023): agents that collect their own trajectories and extract natural-language insights from them. The academic version of the compaction step.
The Memory Bank pattern: a popular markdown-memory methodology from the AI-IDE world. It solves a neighboring problem: Memory Bank reconstructs project state (what we're building, where we stopped), while this workflow accumulates lessons (what must never happen again). The two combine well.
Compounding engineering (Every): the same philosophy ("each unit of work should make the next one easier") grown into a full Claude Code plugin with a Plan, Work, Review, Compound cycle. A packaged alternative to the three prompts here.
Self-improving coding agents (Addy Osmani, 2026): a survey of the looped variants, learnings.md files and continuous loops included.

Steal it

The whole system is three prompts and one pointer line. Nothing is specific to Claude Code except the CLAUDE.md filename; Cursor rules, Windsurf rules, or a plain AGENTS.md work the same way.

Put the hard pointer on the first line of your agent's entry-point file.
Planned work: Prompt 1 to start the run, Prompt 2 when the plan is done.
Everything else: Prompt 3 at the end of the session, before you close it.

🚀 Start on an existing project today: run Prompt 3 at the end of your next session and you'll have your first guardrails by tonight. Five sessions from now, your agent will be citing them back to you.

This is part 1 of a build-in-public series. The project this memory system grew on, a full-stack GraphQL store (Next.js 13 + Keystone 6 + PostgreSQL) running in production for $0/month, is what the next parts dissect: the architecture, the deployment, the ISR + live supplier API mechanics.

I added a RAG-powered AI chat to my landing page - and it's 100% free

vavilov2212 — Sun, 21 Jun 2026 01:20:29 +0000

I added a free RAG-powered AI chat assistant to the Worklog Studio landing page, built with Next.js, the Gemini API, and deployed on Vercel. Here's what it does and why I bothered.

TL;DR;

You can explore source code for this project at a public github repo here.

Why bother with a chat assistant

First of all - it's fun! But really, nobody reads large pieces of text anymore. Having a chatbot that knows your product is a way to motivate users to engage with what you're trying to deliver.

The hard rule I set for myself: the assistant has to admit when it doesn't know something. A chatbot that confidently invents a feature that doesn't exist is worse than no chatbot at all.

How it's wired together

A browser sends a question to a Next.js route running on Vercel. That route checks a rate limiter, pulls the most relevant chunks out of a small precomputed file of embeddings, and sends those chunks plus the question to Gemini. The answer streams back the same way it came in.

Two entry points on the page (an inline box and a header button) share the same chat panel and the same conversation, so switching between them mid-conversation doesn't lose anything.

There's no vector database, it does not use an app database, and does not need user accounts. Conversation history lives in sessionStorage.

What is Worklog Studio?

Worklog Studio is a small desktop time tracker. As of now it's a bare minimum to be useful. Projects, tasks, time entries - you can comment on each entry so you remember what you were actually doing.

I built it because every existing tracker I tried was either missing something or too cluttered with features I don't need. It's open source, and if you want to poke around or contribute, here's the repo: github.com/vavilov2212/wl-studio.

Why it needed a real server

The site used to ship as a static export on GitHub Pages, which is fine for plain content but can't run any backend code. This feature needs one, because the Gemini API key has to stay on the server. Put that key in client-side code and anyone with dev tools open can grab it in five seconds.

So the site moved to Vercel. It is Next.js app on the same repo, and deploy does not change.

What it costs: nothing

Service	Used for	Tier
Vercel	hosting + the API route	Hobby (free)
Gemini API	embeddings + chat	free tier, no GCP project needed
Upstash Redis	rate limiting	free tier

The Gemini key comes from the consumer AI Studio flow, not the Vertex AI console. I'll get into why that distinction matters in part 3.

Up next

I'm splitting this into three posts because there's enough here to get lost in:

Part 2: the actual RAG pipeline, chunking and embedding your own content and how the retrieval code decides when to say "I don't know" instead of guessing. No vector database involved at this point.
Part 3: working with the Gemini API specifically, free tier vs. Vertex AI, and what happens when a model is overloaded.

The site's repo is worklog_studio_site if you want to follow along, and Worklog Studio itself is open for contributions if time tracking is your thing.

Try the assistant yourself: worklog-studio-site.vercel.app. Click "Ask AI" and see what it knows.

🕵️‍♂️ The Case of the Missing S3 Metadata: A CORS Deep Dive

vavilov2212 — Thu, 20 Nov 2025 21:15:09 +0000

When you upload a file to S3 with custom metadata (like fileName or uploadedAt), everything looks correct in the AWS Console. But when you try to read that metadata from your frontend using HeadObjectCommand, the data clearly exists on the cloud, yet the AWS SDK response returns empty Metadata object.

There's a resolved GitHub issue on one of the JavaScript AWS packages.

This is not an bug, the cause isn’t in the AWS SDK or your upload logic. It comes from the browser, and specifically how it handles cross-origin requests.

The rest of this article breaks down where this behavior comes from and how to fix it.

If you read my earlier article, “Stop Uploading Files to S3 the Wrong Way”, you saw a complete example of how to upload and download files efficiently using the AWS SDK with a client/server flow.

This article builds directly on top of that and acts as a follow-up for developers searching for “client-side S3 metadata not showing” issues.

This is Part 2 in a small S3 series
Client and Server behave differently
Why no Metadata on the Client
How to Fix It with S3 CORS Rules

This is Part 2 in a small S3 series

In the first part, the focus was sending and retrieving files. Here, we look at reading custom metadata from a cloud S3 provider in the browser.

You don’t need to read Part 1 to follow this article, but both posts fit together if you’re building a file upload pipeline end-to-end.

Client and Server behave differently

The issue only shows up in certain execution environments, so it helps to look at how the same code behaves in your backend (when it runs on the server) versus in the browser.

Server-side (✅ works as expected)

When HeadObjectCommand runs in a nodejs backend environment - for example, a Next.js API route - it returns the full metadata without any issues. Server-to-server requests aren’t limited by browser security rules, so all response headers are available.

// src/app/api/s3/private/meta/route.ts
import { s3Service } from '../../_lib';

export const GET = async (req: NextRequest) => {
  const documentKey = request.nextUrl.searchParams.get('key') as string;
  const metadata = await s3Service.getMetadata(documentKey);
  return NextResponse.json(metadata);
};

Client-side (❌ metadata comes back empty)

The problem appears when the same request is made from browser JavaScript.
The call succeeds, but the Metadata object in the AWS SDK response is empty.

// src/app/api/s3/_lib/s3Service.ts
export const getFileMetadata = async (id: string) => {
  const response = await s3.send(
    new HeadObjectCommand({
      Bucket: bucketName,
      Key: id,
    })
  );

  return response.Metadata; // {} without proper CORS
};

// src/components/File.tsx
useEffect(() => {
  async function setFilename() {
      const fileMetadata = await getFileMetadata(file.documentId);
      return {
        ...contract,
        // fileMetadata is empty, so this becomes undefined
        filename: fileMetadata?.filename,
      };
    });
  }
  setFilename();
}, [file]);

The request itself isn’t failing. S3 returns the metadata correctly.
But because the code runs in the browser, certain response headers - including S3’s custom metadata headers - are not exposed to JavaScript by default.

The next section explains why this happens.

Why no Metadata on the Client

Two fundamental security mechanisms are involved here: the Same-Origin Policy (SOP) and Cross-Origin Resource Sharing (CORS).

S3 CORS expose headers, custom metadata missing browser, or AWS CORS not working.

1. Same-Origin Policy

Browsers enforce a rule that pages can only freely access resources from the same “origin,” defined by scheme, host, and port.
Your frontend (https://your-app.com) and S3 (https://your-bucket.s3.amazonaws.com) are different origins, so the browser restricts what your code can access.

2. CORS as the exception

CORS is a system that allows a server to relax these restrictions.
If you configure S3 with an AllowedOrigin matching your frontend, the browser is permitted to make the request.

However, this only covers whether the request can happen - not what the browser exposes back to your JavaScript.

3. Access-Control-Expose-Headers

Even with CORS enabled, the browser only exposes a small set of safe default headers to the client.
S3’s custom metadata headers (x-amz-meta-*) are not part of that list.

This means:

S3 sends the metadata correctly.
The browser receives it.
But the browser filters it out or hides it before the AWS SDK gets the response.

The SDK sees no metadata headers and correctly (from its perspective) returns an empty Metadata object. Unless your S3 bucket explicitly exposes the metadata headers through CORS, your client code will always see Metadata: {}.

How to Fix It with S3 CORS Rules

How do I fix S3 CORS so metadata shows up in HeadObject?

To make your metadata visible in the browser, you need to add your metadata fields to Access-Control-Expose-Headers in your S3 bucket’s CORS config so the browser is allowed to expose the headers you care about.

Add them to its HEAD request responses. This is done by updating the CORS configuration on your S3 bucket, as detailed in the official Amazon S3 User Guide on Managing CORS.

A working XML example looks like this:

<!-- S3 Bucket CORS Configuration (XML) -->
<CORSConfiguration>
  <CORSRule>
    <AllowedOrigin>https://your-app.com</AllowedOrigin>
    <AllowedMethods>GET</AllowedMethod>
    <AllowedMethods>HEAD</AllowedMethod>
    <AllowedHeaders>*</AllowedHeader>
    <ExposeHeaders>x-amz-meta-filename</ExposeHeader>
    <ExposeHeaders>x-amz-meta-uploaded-by</ExposeHeader>
    <!-- Add an <ExposeHeader> for each custom metadata key you use -->
  </CORSRule>
</CORSConfiguration>

JSON Configuration Example:

// S3 Bucket CORS Configuration (JSON)
{
  "CORSRules": [
    {
      "AllowedOrigins": ["<https://your-app.com>"],
      "AllowedMethods": ["GET", "HEAD"],
      "AllowedHeaders": ["*"],
      "ExposeHeaders": ["x-amz-meta-filename", "x-amz-meta-uploadedat"]
    }
  ]
}

This enables client-side S3 HeadObject to return the full metadata object.

A few important details:

Expose only the headers you need. The browser will ignore everything else.
HEAD and GET both matter. If you’re calling HeadObjectCommand from the client, the HEAD method must be included or the request may fail depending on your setup.
Wildcard AllowedHeaders is fine here. It simply allows the browser to send custom headers, not expose them.

After this configuration is applied, the browser will no longer filter out the metadata, and your AWS SDK call will return the full Metadata object instead of {}.

👉 Missed Part 1?
Read the full upload/download pipeline here: Stop Uploading Files to S3 the Wrong Way

🚀 Stop Uploading Files to S3 the Wrong Way

vavilov2212 — Tue, 14 Oct 2025 01:12:53 +0000

When you let users upload files to S3, the most intuitive solution is to create an API route that accepts a file and uses the aws-sdk on the server to forward it to your bucket. This way each file transfer is done twice (2x) consuming resources and creating a bottleneck.
Uploading files directly from the browser can save your server’s bandwidth and simplify infrastructure. Here’s how to do it securely and cleanly with react and Next.js.

TL;DR
Motivation
Disposition
The Core: server operates entities
Step 1: The Server Side API Route for Uploads
Step 2: A Decoupled Client Side Architecture
- The Data Access Layer
- The Business Logic Layer
Step 3: Implementing Secure Downloads
- A Deeper Look at the Client Side Download
Handling Environment Variables
Where to go from here?

TL;DR

If you know what you’re doing and just need a working example reference, here you can find the complete code used in this article.
This guide covers a secure file upload to S3 using react, next.js and AWS SDK v3 with pre-signed URLs.

Motivation

The react next.js frontend app lets users perform a secure file upload to S3 directly from the browser and let them have access to those files afterwards. Pretty straightforward feature, but let’s get deeper:

There is an operations or support team that reviews those files in an internal admin board (e.g. verify contracts, evaluate numbers in reports etc.)
These files contain sensitive information and can not be accessed publicly.
The client user can only see his files and not other user’s files.

Instead of implementing your own static server solution, you can delegate storing and serverless file management to any S3-compatible object storage.

Disposition

Whether you’re using Amazon S3, DigitalOcean Spaces, Linode Object Storage etc., this applies to any S3-compatible storage service. In order to upload and read files, we can use @aws-sdk/client-s3 for S3 compatible Object Storage.

The most intuitive solution is often to create an API route that accepts a file and then uses the AWS-SDK on the server to forward it to your bucket. This server proxy makes your application the bottleneck.



  +------------------+       +---------------+       +---------------+
  │  Client Browser  │  →→→  │  Your Server  │  →→→  │   S3 Bucket   │
  +------------------+       +---------------+       +---------------+
         │                         │
   (1) Upload File           (2) Forward File
         │                         │
         ↖─────────────────────────↗
              File travels twice

Every uploaded megabyte must be processed by your server, consuming its bandwidth and memory, before being sent on to S3. The file is transferred twice potentially exceeding memory or execution time limits (for large files).

The same happens when a user downloads a file.

The industry-standard solution is to offload this work by letting the client (browser) upload directly to S3.

The Core: server operates entities

Instead of doing the heavy lifting, your api route performs a quick, secure handshake.

The Client Requests an Upload: Your front-end makes a small API call to your server, providing metadata like the file's content type (MIME type).
The Server Generates a pre-signed URL: Your server which safely stores your s3 credential uses the SDK to generate a temporary, single-use URL with specific permissions (e.g., "allow a PUT operation for image/png for the next 10 minutes").
The Client Uploads Directly to S3: The client receives this URL and uses it to send the file straight to S3, bypassing your server entirely.

                     +----------------------+
                     |      Your Server     |
                     | (Auth + Signed URLs) |
                     +----------+-----------+
                                ↕
                +---------------+---------------+
                |                               |
      (1) Request Upload URL           (1) Request Download URL
                |                               |
                ↓                               ↓
          +-----+-----+                   +-----+-----+
          |  Client   |                   |  Client   |
          | (Browser) |                   | (Browser) |
          +-----+-----+                   +-----+-----+
                |                               |
     (2) Upload File using URL       (2) Use URL to Download File
                |                               |
                ↓                               ↓
          +-----+-----+                   +-----+-----+
          |    S3     |   ←–––––––––––→   |    S3     |
          | (Storage) |  (3) File Stored  | (Storage) |
          +-----------+                   +-----------+

This pattern is secure, highly scalable, and more cost-effective. Let’s build this step by step.

The following code examples are taken from a Next.js project that uses Feature-Sliced Design (FSD) for its architecture.
You can follow along with the complete, working code in the example repository linked above.

Step 1: The Server Side API Route for Uploads

This Next.js API route for S3 uploads, validates the request and generates the pre-signed URL. It's also the perfect place to enforce business logic, like attaching metadata.

// src/app/api/upload/route.ts

import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
import { NextResponse } from "next/server";
import crypto from "crypto";

// --- This is a placeholder for your authentication logic ---
// In a real app, you would get the user's session from the request
// headers, cookies, or a token.
async function getUserIdFromSession(request: Request): Promise<number> {
  // Example: return the user ID from your auth system (e.g., NextAuth, Clerk)
  // For now, we'll return a hardcoded ID.
  return 123; 
}
// -------------------------------------------------------------

// This is safe to initialize here as it only runs on the server.
const s3 = new S3Client({
    region: process.env.S3_REGION!,
    endpoint: `https://${process.env.S3_ENDPOINT!}`,
    credentials: {
        accessKeyId: process.env.S3_ACCESS_KEY_ID!,
        secretAccessKey: process.env.S3_SECRET_ACCESS_KEY!,
    },
});

export async function POST(request: Request) {
    try {
      const { contentType } = await request.json();

      // const userId = 123; // In a real app, derive this from the user's session.
      // 1. Get the current user's ID securely on the server
      const userId = await getUserIdFromSession(request);

      const key = crypto.randomBytes(16).toString("hex");

      const command = new PutObjectCommand({
        Bucket: process.env.S3_BUCKET_NAME!,
        Key: key,
        ContentType: contentType,
        Metadata: {
          uploadedBy: userId.toString(),
          uploadedAt: new Date().toISOString(),
        },
      });
      const signedUrl = await getSignedUrl(s3, command, { expiresIn: 600 }); // URL is valid for 10 minutes
      return NextResponse.json({ signedUrl, key });
    } catch (error) {
      // ...error handling
    }
}

This API route is the foundation for secure serverless file uploads in any Next.js + AWS S3 SDK integration.

Step 2: A Decoupled Client Side Architecture

To keep our code clean and testable, we'll separate frontend file upload logic from the business logic.

The Data Access Layer

This file's only job is to execute fetch requests. It handles how we communicate with our APIs.

// src/shared/api/s3.ts

// Requests a pre-signed URL from our backend.
export async function getPresignedUrl(contentType: string): Promise<{ signedUrl: string; key: string }> {
    const response = await fetch('/api/upload', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ contentType }),
    });

    if (!response.ok) throw new Error('Failed to get pre-signed URL.');

    return response.json();
}

// Uploads the file to the provided S3 URL.
export async function uploadToS3(signedUrl: string, file: File): Promise<void> {
    const response = await fetch(signedUrl, {
        method: 'PUT',
        body: file,
        headers: { 'Content-Type': file.type },
    });

    if (!response.ok) throw new Error('S3 upload failed.');
}

The Business Logic Layer

This file defines what the feature does - the sequence of steps - without knowing the implementation details.

// src/features/file-management/model/uploadFile.ts

import { getPresignedUrl, uploadToS3 } from "@shared/api/s3";

// This function orchestrates the upload process.
export async function uploadFile(file: File): Promise<{ success: boolean, key?: string }> {
    try {
        const { signedUrl, key } = await getPresignedUrl(file.type);
        await uploadToS3(signedUrl, file);

    // Step 3: Upload file key to store in database
    // console.log("Uploading file key to store in database...");
    // await storeUploadedFileKey(key, additionalData);

        return { success: true, key };
    } catch (error) {
        console.error("Upload failed:", error);

        return { success: false };
    }
}

With this separation, your UI component only needs to import and call uploadFile(theFile). The component remains simple, and your logic is reusable and easy to unit test.

Step 3: Implementing Secure Downloads

The download flow uses the same secure pattern. First, we create an API route to generate a pre-signed GetObject URL for a secure S3 file download.

// src/app/api/download/route.ts

import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3";

// ... s3 client setup is the same ...

export async function GET(request: NextRequest) {
    const key = request.nextUrl.searchParams.get('key');

    if (!key) { /* handle error */ }

    const command = new GetObjectCommand({
        Bucket: process.env.S3_BUCKET_NAME!,
        Key: key,
        // This header forces the browser to download the file.
        ResponseContentDisposition: `attachment;`
        // You can override the filename for the user here
        // But then you must also know the file extension
        // ResponseContentDisposition: `attachment; filename="${key}"`
    });

    const signedUrl = await getSignedUrl(s3, command, { expiresIn: 300 }); // 5 minute validity
    return NextResponse.json({ signedUrl });
}

Now for the client-side, which involves a browser hack to trigger the download without navigating away from the page.

// src/features/file-management/model/downloadFile.ts

import { getDownloadUrl } from "@shared/api/s3"; // Assumes a getDownloadUrl function in the shared API layer

// This function orchestrates the business logic for downloading a file.
export async function downloadFile(key: string): Promise<{ success: boolean }> {
    try {
        // Step 1: Get the pre-signed download URL
        const { signedUrl } = await getDownloadUrl(key);

        // Step 2: Trigger the download in the browser
        const link = document.createElement('a');
        link.href = signedUrl;
        link.setAttribute('download', key);
        document.body.appendChild(link);
        link.click();
        document.body.removeChild(link);

        return { success: true };
    } catch (error) {
        console.error("File download process failed:", error);

        return { success: false };
    }
}

Together, these steps form a scalable, production-ready file upload and download workflow using react Next.js, TypeScript, and AWS S3 SDK.

A Deeper Look at the Client Side Download

You might be wondering about the link.click() part. Why not just use window.location.href = signedUrl?

First, a direct navigation would rip the user out of your single-page application. Second, for content types the browser can render (like images, PDFs, or text files), it would likely just display the file instead of saving it.

The programmatic anchor tag (<a>) solves both problems:

const link = document.createElement('a'); We create a new, invisible link element in memory.
link.href = signedUrl; We set its destination to our secure, temporary S3 URL.
link.setAttribute('download', key); This is the most important part. The download attribute is a command to the browser: "Do not navigate to this href. Instead, treat its content as a file to be saved, and use this attribute's value as the suggested filename." This forces the download behaviour.
document.body.appendChild(link); The link must be attached to the document for it to be clickable.
link.click(); We programmatically simulate a user clicking the link, which triggers the browser's "Save As..." dialog.
document.body.removeChild(link); The link has done its job, so we immediately remove it from the DOM to keep our page clean.

Handling Environment Variables

As a final note, manage your credentials using a .env file and provide a template for other developers with a .env.example. Be sure to add .env to your .gitignore.

# .env.example

# S3 Configuration

S3_BUCKET_NAME=your-s3-bucket-name
S3_REGION=your-bucket-region
S3_ENDPOINT=your-s3-endpoint
S3_ACCESS_KEY_ID=your-access-key-id
S3_SECRET_ACCESS_KEY=your-secret-access-key

Proper environment variable management for credentials is crucial for a secure S3 integration in any web app that uses serverless solutions.

Where to go from here?

Once a file is in your S3 bucket, the next logical step is often to trigger serverless functions based on S3 events (e.g. S3 automation, Lambda triggers, and object storage workflows).

You could:

Generate thumbnails for uploaded images.
Transcode files into different formats.
Run data processing jobs on uploaded files.
Notify other services that a new file is available.

👇 Please share how you treat user-provided data?

Do you analyse it with metrics? If so, what kinds of insights are you looking to uncover?

Thanks for reading!

Enforce Module Imports in FSD (using eslint-plugin-import)

vavilov2212 — Mon, 22 Sep 2025 02:21:17 +0000

Have you ever refactored a project and realised every file had a different import style? This article dives deeper into managing code structure by enforcing rules with ESLint.

TL;DR
Motivation
Unforeseen Consequences
Enforcing Code Structure
Customising the Rule
Future Exploration

TL;DR

If you already know what you’re doing, check out the example repo: eslint-fsd-example. It follows the FSD (Feature Sliced Design) and serves as a practical showcase.

Motivation

As a lead developer, one of my responsibilities is to ensure that the codebase stays coherent and manageable while complexity grows. When new features and fixes are introduced by a team of developers, it’s inevitable that their code looks different. That’s fine — each one brings a unique vision and perspective. Sometimes, the team even adopts those practices at scale.

But coding style and structure are another story. Everyone has their own vision, and that’s great… until you want to refactor 😑.

Imagine different parts of your code doing things their own way:

import ... from "shared/ui/Comment"; // baseUrl + direct file
import ... from "../../ui/Comment";  // relative path
import ... from "@/shared/ui";       // alias + index file
import ... from "../../ui/index.js"; // relative path to index
// and so on

This happens in real projects and leads to a zoo of approaches scattered everywhere. Problems include circular imports, and broken refactors (auto-import often fails to replace paths correctly).

Unforeseen Consequences

Circular imports often appear when you import from an index file that re-exports the same module:

// src/shared/ui/index.js
export * from './Comment';
export * from './Like';
export * from './ViewsCounter';

// src/shared/ui/Comment
import ... from 'shared/ui'; // <-- 🔥 causes a cycle

Or even without an index file:

// src/shared/ui/Comment
import ... from './Like';
// src/shared/ui/Like
import ... from './ViewsCounter';
// src/shared/ui/ViewsCounter
import ... from './Comment';

💡 This can even lead to runtime errors that are very hard to debug (ask me how i know it).

Enforcing Code Structure

FSD conventionally enforces strict import/export principles (they’re even described as mandatory in the docs):

Any module may only be imported via its public API (index file) using an absolute path
Inside a module, all imports must use relative paths (avoids cycles)

But what stops developers from breaking this rule? Nothing 🤔 — unless you enforce it with ESLint.

FSD provides a dedicated feature-sliced/eslint-config with just three rules:

public-api – uses eslint-plugin-import, adds glob expression to match patterns in your import statements (internally then converts glob expressions to regexp via minimatch )
layers-slices – uses eslint-plugin-boundaries, analyses relations between the dependent element (your module) and the dependency (what’s being imported) and checks if it’s allowed or not (see fsd docs)
import-order – uses eslint-plugin-import, sorts and groups imports alphabetically

Let’s take a look at a Next.js example project that tries to follows FSD (Feature Sliced Design) methodology. Boilerplate comes from create-next-app using the with-eslint example.

npx create-next-app \
eslint-fsd-example \ # project name
-e https://github.com/vercel/next.js/tree/canary \ # example name or url
--example-path examples/with-eslint # if example url has a branch name in it and then path to the example, it has to be specified separately

Customising the Rule

Project structure (simplified):

src/
├── app/
│   ├── ...
│   ├── page.tsx
│   │   └── Home page
│   └── signin/
│       └── page.tsx
│           └── Signin Page
├── _pages/
│   └── signin/
│       └── ui/
│           ├── index.ts
│           ├── views/
│           │   ├── Signin.tsx
│           │   │   └── Signin main container
│           │   └── index.ts
│           └── components/
│               ├── index.ts
│               └── Signin/
│                   ├── Signin.tsx
│                   │   └── Signin actual content
│                   └── index.ts
├── _features/
│   └── sigin/
│       ├── types/
│       │   ├── index.ts
│       │   └── signinFormValues.ts
│       └── lib/
│           ├── index.ts
│           └── useSigninForm.ts

The _pages and _features folders start with underscores to avoid naming conflicts with Next.js reserved folders. Other FSD layers use the same convention for consistency.

We want to enforce imports only from public APIs (index files). Here’s a simplified ESLint config:

const FS_LAYERS = [ 'entities', 'features', 'widgets', 'app', 'processes', 'pages', 'shared' ];

const FS_SEGMENTS = [ 'ui', 'types', 'model', 'lib', 'api', 'config', 'assets' ];

const nextjsConfigRules: Linter.Config['rules'] = {
  'import/no-internal-modules': [
    'error',
    {
      allow: [
        /**
         * Allow not segments import from slices
         * @example
         * 'entities/user/ui' // Pass
         * 'entities/user' // Also Pass
         */
        `**/*(${FS_SLICED_LAYERS_REG})/!(${FS_SEGMENTS_REG})/*(${FS_SEGMENTS_REG})`,

        /**
         * Allow slices with structure grouping
         * @example
         * 'features/auth/form' // Pass
         */
        `**/*(${FS_SLICED_LAYERS_REG})/!(${FS_SEGMENTS_REG})/!(${FS_SEGMENTS_REG})`,
        ...
      ],
    }
  ]
};

💡 For the shared directory different rules apply since it’s somewhat special.
Look in the source code for details.

Reaching past src/_features/signin/lib/index.ts is prohibited — exactly what we want ✅.

Here’s the proof:

The FSD guidelines say you should only import from the slice root. Our team, however, prefers to allow imports from specific segments (like ui, lib, etc.).

To achieve this, we had to adjust eslint-plugin-import directly.

If you want to follow the official FSD recommendations, you can just use the feature-sliced/eslint-config public-api rule as is.

Future Exploration

While this setup covers the basics of enforcing FSD imports, there are still some open questions worth exploring:

Cross-imports with @x in FSD – Cross-imports are part of the official FSD methodology. They allow integration between slices or layers in a controlled way. But how do we enforce them properly with ESLint, and what are the best practices for keeping them consistent?
Dynamic imports – Sometimes you need to use import() directly for code-splitting. But what happens when you want to dynamically import something from a public API instead of a deep file? Is that possible, or do you always end up importing the raw file?
Testing strategies – Should tests respect the same public API import rules, or is it acceptable for them to reach into private modules?

I don’t have all the answers yet (still experimenting 😅), but these are areas I’m actively digging into.

👉 In a follow-up post, I’ll share experiments and possible solutions for:

Making dynamic imports work with public APIs
Handling test imports without breaking conventions
Enforcing and scaling cross-imports without losing clarity

So if that sounds interesting — stay tuned, because Part 2 is coming!

👇 Share your experience in the comments — I’d love to hear how you handle these challenges!

🧠 Master Your Prompt: A Practical Process to Improve AI Interactions

vavilov2212 — Fri, 11 Jul 2025 00:36:29 +0000

Step-by-Step Guide to Analyze and Enhance Your Prompts:

In today’s AI-driven world, the precision and structure of input prompts directly influence output quality, relevance, and consistency. Effective prompt engineering is a critical skill for developers, data scientists, and AI practitioners aiming to optimize model performance and reduce ambiguity. This article presents a practical, step-by-step process to analyze, refine, and enhance your prompts—helping you unlock the full potential of AI interactions.

📄 The Original Prompt

The full prompt in text format → Prompt Refiner or click the image 👇

🎥 Source

I stumbled upon this prompt structure on Social media and titled as "The World's best AI methods" by a content creator who sells prompt libraries.

🌤️ Strong Design (for reference)

Clear, modular 2-phase structure
Low cognitive load with simple diagnostics
Deliverables are copy/paste-friendly
Useful for tooling and collaborative workflows

‼️ Flaws and How to Enhance

1. ⚡️ Assumes intent is always worth preserving

⚠️ It prioritizes retaining original intent, even when that intent is vague or misguided.
But in real-world usage, input prompts are often vague, contradictory, or low-quality.

Example: “Make it cool and viral.” What does that mean? Tone? Format? Medium?

✅ Add an early clarification step:
“If the original intent is unclear, poorly defined, or counterproductive, rewrite the goal before proceeding.”

2. ⚡️ No fallback logic for poor or minimal inputs

⚠️ You can't go forward if the prompt is unusable.
It should trigger structured fallback behavior, but there's none.

Example:
- Extremely short prompts (“Make it nice”)
- Prompts lacking context (“Write an article”)
- Unstructured lists without instruction

✅ Insert a Phase 0 – Precheck step:
“If input prompt lacks purpose, audience, or content type, request clarification before continuing.”

3. ⚡️ Doesn’t distinguish prompt types (creative vs. functional)

⚠️ The same criteria are applied to all prompt types.
Prompts for storytelling or ideation shouldn’t be judged by the same standards as instructional prompts.

Example: A story prompt might intentionally break clarity or tone norms to achieve voice, metaphor, or ambiguity.

✅ Add a Prompt Type Detection step:
“If prompt appears to be creative, conversational, or open-ended, adapt evaluation criteria. Skip irrelevant items like accuracy or resource usage.”

4. ⚡️ No resolution strategy for conflicting criteria

⚠️ In practice, criteria can contradict each other:
• Improving clarity may reduce brevity
• Strengthening tone may hurt resource efficiency
• Increasing specificity might restrict flexibility

There’s no prioritization

✅ Define a default priority order: Clarity → Tone → Brevity → Efficiency
“If two criteria conflict, prioritize the one that maximizes usefulness and comprehension.”

🛠️ Enhanced Prompt

The full prompt in text format → Prompt Refiner Enhanced or click the image 👇

🚀 Would You Trust This?

Community Insights Welcome!

👉 Drop your thoughts below. I’ll reply to every comment.

From @import to @use: Migrating Sass the Right Way in a Next.js Project

vavilov2212 — Wed, 02 Jul 2025 02:21:53 +0000

TL;DR: Sass Migration in a Nutshell

Still using @import in your SCSS? Time to level up. Here’s what I did:

✅ Replaced @import with @use 'styles/...' as *

🛠️ Added resolving Sass Paths for cleaner imports

🧪 Verified everything using npx sass-migrator — no issues found

🧹 Reordered CSS declarations above nested rules to remove deprecation warnings

📁 Renamed confusing css/ folder to styles/ for clarity

🧘‍♂️ Result: No more terminal spam, cleaner code, and a future-proof SCSS setup

When working on a growing frontend project using Next.js and Sass/SCSS, it’s easy to miss the warnings piling up in the console — until they become impossible to ignore.

Recently, I took on the task of cleaning up a Next.js codebase that was riddled with deprecated @import usage and upcoming breaking changes related to how nested declarations behave. Here’s how I approached it, what I learned, and how you can apply it to your project.

🚨 Why Migrate from `@import`?

💡 The @import rule is deprecated and will be removed in future versions of Sass. Use @use or @forward instead.

sass-lang.com/documentation/breaking-changes/import/

You may still see @import sprinkled throughout your .scss files, and while it works for now, it comes with hidden costs:

Unpredictable global scoping
No clear module boundaries
Duplicate style injection
Tons of warnings in your terminal and browser console

In my case, the project had @import '~css/colors' and similar statements all over .module.scss files. The tilde (~) was working magically, resolving to the src/ folder — although we never explicitly configured that (likely a leftover from legacy webpack behavior).

🔁 The `@use` Syntax

The new module system introduced by Sass is smarter, safer, and designed to prevent namespace collisions. Here’s how I migrated:

✅ Before

@import '~css/colors';
@import '~css/vars';
@import '~css/mixins';

✅ After

@use 'styles/colors' as *;
@use 'styles/vars' as *;
@use 'styles/mixins' as *;

Along the way, I also renamed the folder from css/ to styles/ — it just makes more sense semantically and reads better for anyone joining the project.

🧭 Resolving Sass Paths in Next.js

To avoid long relative imports like ../../styles/colors, I initially configured the project like this:

// next.config.mjs
import path from 'path';

export default {
  sassOptions: {
    includePaths: [path.join(__dirname, 'src')],
  },
};

This allowed me to write clean import statements such as:

@use 'styles/colors' as *;

✅ It worked.

⚠️ But there’s more you should know.

❗includePaths Is a Legacy Pattern

While includePaths is still supported by Dart Sass (and by the sassOptions field in Next.js), it’s not ideal for long-term use — especially with modern Sass modules.

💡 “The includePaths option is not recommended for use with @use. Instead, prefer using relative or package-based URLs.”
sass-lang.com/documentation/at-rules/use/#url

🧩 Better Path Resolution Options

✅ 1. Use Relative Paths (Recommended)

Instead of relying on global resolution, you can write:

@use '../../styles/colors' as *;

It’s a bit more verbose, but it’s:

Explicit ✅
Native to Sass ✅
Portable across tools ✅

✅ 2. Use Webpack Aliases (Optional, with Caveats)

If you want clean, short import paths and you’re using Next.js with Webpack, you can configure an alias:

// next.config.mjs
import path from 'path';

export default {
  webpack(config) {
    config.resolve.alias['@styles'] = path.join(__dirname, 'src/styles');
    return config;
  }
};

Then in SCSS:

@use '@styles/colors' as *;

⚠️ Sass doesn’t know what @styles means unless your tooling resolves it (e.g. via sass-loader in Webpack).

✅ 3. Use the SASS_PATH Environment Variable

Define your base path globally using an environment variable.

In a .env file:

SASS_PATH=src

Then in your SCSS:

@use 'styles/colors' as *;

This works in Next.js and many other Sass toolchains, and is a nice middle ground between global includes and explicit paths.

✅ Built-in support

✅ Cleaner imports

⚠️ Slightly hidden magic

📚 node-sass on GitHub

🛠 Using sass-migrator to Validate Migration

Sass provides a handy CLI tool to help you migrate - sass-migrator

Here’s what I ran:

npx sass-migrator module --migrate-deps -I ./src ./src/**/*.scss

# stdout
Nothing to migrate!

Which meant my manual changes were already valid under the module system — a good sanity check after a global find-and-replace in VSCode.

🔃 Fixing Declaration Order in Nested Rules

Another warning that was spamming my console came from how some SCSS blocks had declarations after nested selectors. Sass is aligning more with CSS behavior here.

📚 More info here: https://sass-lang.com/documentation/breaking-changes/mixed-decls/

The fix? Move all property declarations above nested selectors.

⚠️ Deprecated Style

.fee {
  display: flex;
  align-items: center;

  &Text {
    color: var(--txt2);
  }

  gap: 6px;
}

✅ Fixed Style

.fee {
  display: flex;
  align-items: center;
  gap: 6px;

  &Text {
    color: var(--txt2);
  }
}

🧹 Final Thoughts

This was a small but meaningful refactor that:

Removed console spam
Future-proofed our stylesheets
Improved module clarity
Made onboarding easier

If you’re using Sass in 2025, migrating to @use isn’t just a nice-to-have If you’re maintaining a similar setup in Next.js. I highly recommend doing this migration sooner than later. It took me a couple of commits.

🔀 macOS Split-Tunneling VPN Guide: Route Only Specific Subnets

vavilov2212 — Sat, 14 Jun 2025 09:15:56 +0000

Many remote developers need to access company-internal services behind a VPN. The standard VPN setup? Connect using L2TP over IPsec.

But that usually routes all your traffic through the VPN — from websites to updates and personal apps.

😬 Not ideal when you only need access to a specific internal subnet.

Let’s fix that with this split tunneling guide.

🧠 What Is Split Tunneling?

Split tunneling means routing only specific IP ranges (like your company subnet) through the VPN, while everything else uses your normal internet connection.

Example:

Internet traffic  ─────────► stays local
Internal subnet   ─────────► goes through VPN

This results in:

⚡ Better internet performance
🔒 Better privacy
🎯 More precise access to internal resources

❗ Default VPN Behavior on macOS

If you're using System Settings > Network to connect via L2TP over IPsec:

macOS routes all traffic through the VPN once connected
There’s no tun/ppp interface visible in ifconfig
No native UI option for split tunneling

🔧 How To Manually Add a Route

Let’s say:

Your internal company subnet is <YOUR_SUBNET> (e.g., 192.168.50.0/24)
Your VPN gateway IP is <VPN_GATEWAY_IP> (e.g., 10.8.0.1)

After connecting to VPN:

sudo route -n add <YOUR_SUBNET> <VPN_GATEWAY_IP>

🔍 Example:

sudo route -n add 192.168.50.0/24 10.8.0.1
# ✅ Expected output:
# add net 192.168.50.0: gateway 10.8.0.1

⚙️ Automating with `/etc/ppp/ip-up`

Let’s automate route setup when PPP-based VPN connects.

Create a new script:

sudo nano /etc/ppp/ip-up

Paste this:

#!/bin/sh
# /etc/ppp/ip-up is triggered after a successful VPN connection
# $5 is the VPN gateway IP passed by macOS

VPN_GATEWAY="<VPN_GATEWAY_IP>"  # e.g., 10.8.0.1
TARGET_SUBNET="<YOUR_SUBNET>"   # e.g., 192.168.50.0/24

if [ "${5:-}" = "${VPN_GATEWAY}" ]; then
    /sbin/route -n add -net $TARGET_SUBNET $5 > /tmp/ppp.log 2>&1
fi

Make it executable:

sudo chmod +x /etc/ppp/ip-up

📄 The script logs output to:

sudo cat /tmp/ppp.log

🧼 Optional: Cleaning Up with `/etc/ppp/ip-down`

To remove the route automatically when VPN disconnects:

sudo nano /etc/ppp/ip-down

#!/bin/sh
VPN_GATEWAY="<VPN_GATEWAY_IP>"  # e.g., 10.8.0.1
TARGET_SUBNET="<YOUR_SUBNET>"   # e.g., 192.168.50.0/24

if [ "${5:-}" = "${VPN_GATEWAY}" ]; then
    /sbin/route -n delete -net $TARGET_SUBNET $5
fi

Make it executable:

sudo chmod +x /etc/ppp/ip-down

📡 How to Test If the Route Works

1. Check the Routing Table

netstat -nr | grep <YOUR_SUBNET_PREFIX>

🧪 Example:

netstat -nr | grep 192.168.50
# Expected output:
# 192.168.50.0/24   10.8.0.1        UGSc           25       0     en0

2. Try a Ping

ping <INTERNAL_SERVER_IP>
# Example:
# ping 192.168.50.10
# Expected output:
# 64 bytes from 192.168.50.10: icmp_seq=0 ttl=64 time=30.1 ms

3. Read the Log File

cat /tmp/ppp.log
# Example log:
# add net 192.168.50.0: gateway 10.8.0.1

📝 If there's an error (e.g., gateway not reachable), it will show up here.

🧱 Visual: Full Tunnel vs. Split Tunnel

🔒 Full Tunnel (Default Behavior)

All traffic
    │
    ▼
[ VPN Gateway ] ─────► [ Company Resources ]
      ▲
      │
[ Your System ]──────► Internet (via VPN)

⚡ Split Tunnel (Your Configuration)

[ Your System ]
   │       │
   │       └───────► Internet (direct)
   │
   └───────► VPN Gateway ───► <YOUR_SUBNET>
                         ▲
                         │
                 [ Company Resources ]

❗ What If VPN Pushes a Default Route?

Some VPN servers force your system to route all traffic through them.

To override:

1. Find Your Default Gateway

Before connecting:

netstat -nr | grep default
# Example output:
# default            192.168.1.1        UGSc           86       0     en0

Save this value.

2. After Connecting to VPN

sudo route delete default
sudo route add default <YOUR_LOCAL_GATEWAY>
# Example
# sudo route delete default
# sudo route add default 192.168.1.1

⚠️ Do this with caution — if you get it wrong, you may temporarily lose internet.

✅ Summary

🔌 L2TP/IPsec VPN on macOS routes all traffic by default
🔀 Split tunneling lets you access only what's needed
🛠️ Automate routes with /etc/ppp/ip-up
🧹 Clean up with /etc/ppp/ip-down
🧾 Logs are saved to /tmp/ppp.log
🧪 Testing ensures everything’s working as expected
🚧 Optionally override VPN-pushed routes

🔗 Further Reading

man route
man pppd
Apple VPN Developer Docs

Inject sass global variables from next.config.js - sass env variables

vavilov2212 — Tue, 29 Apr 2025 13:53:40 +0000

Add global variable to sass compiler

with-next-sass - This official next.js example demonstrates how to use Next.js' built-in Global Sass/Scss imports and Component-Level Sass/Scss modules support.

This stackoverflow answears helped me.

Nextjs has built in sapport for sass. To use component isolated .sass or .scss files you need to install sass.

npm install sass

To configure sass compiler you can use sassOptions in next.config.js. nextjs.org/#customizing-sass-options

For instance, if you want to load assets from styles like @font-face src and have different locations on prod and dev environments, you can do the following:

In next config set assetPrefix depending on the environment. Then, add sassOptions variable.

// next.config.js

module.exports = (phase) => {
  // when started in development mode `next dev` or `npm run dev`
  const isDev = phase === PHASE_DEVELOPMENT_SERVER;
  // when `next build` or `npm run build` is used
  const isProd = phase === PHASE_PRODUCTION_BUILD;

  const assetPrefix = isProd ? '/prod' : '/';

  const sassOptions = {
    prependData: `$prefix: "${assetPrefix}";`,
  }

  ... // Other configuration

  return {
    ...
    sassOptions
  };
}

In .scss files now you can use this prefix variable to prepend import paths.

@font-face {
  font-family: 'Open-Sans';
  src: url("#{$prefix}fonts/OpenSans-Regular.ttf");

Sentry Dynamic Environment at Runtime on Client with Next.js

vavilov2212 — Sat, 14 Sep 2024 16:45:21 +0000

This article explores how to configure the Sentry SDK with environment-specific information in a Next.js application.

Exposition

Sentry understands and reads the following environment variables, so you don’t have to explicitly set them in your Sentry SDK init payload (refer to Sentry Docs - Common Config Options):

SENTRY_DSN
SENTRY_ENVIRONMENT
SENTRY_RELEASE

The Challenge with .env variables:

With Next.js, this only works for server side, because the framework DOES NOT expose .env variables on client for security reasons (refer to Next.js Docs - Bundling Environment Variables for the Browser).

Sentry even states this in the environment section of the configuration docs.

In order to distinguish Sentry traces between staging environments on client we need to explicitly set the environment key in the Sentry SDK init payload to a desired value.

Remember, NEXT_PUBLIC variables are hardcoded into JS bundle at build time

// sentry.client.config.js
...

Sentry.init({
  ...

  /*
   * The current environment of your application (e.g. "production").
   * Must be explicitly set, as SENTRY_ENVIRONMENT .env variable is not exposed on client
   */
  environment: process.env.NEXT_PUBLIC_SENTRY_ENVIRONMENT,

  ...
});

As we deploy different staging environments - we need to assign actual names of those environments to our Sentry SDK environment key.

Possible Solutions

Currently there’s no way to natively achieve this in Next.js and people have been struggling with this (check out Github issue - Init with environment config not working)

The official recommended way by Next.js is stated in their documentation Next.js docs - Bundling Environment Variables for the Browser.

If you need access to runtime environment values, you'll have to setup your own API to provide them to the client (either on demand or during initialization).

However, this approach doesn’t work for the Sentry Browser SDK as it's initiated during build time and runs before first components mount (as far as i understand).

But there are multiple other ways to achieve this:

Have multiple builds for each environment - While technically possible, having separate builds for each environment is cumbersome and inefficient and is simply a bad practice (read Build Once, Deploy Many)
Init Client Sentry SDK in Layout Component
Point the tunnel option of Sentry SDK to a proxy and set init values there (found in comments of the discussion from previous entry, but yet to be explored).
Replace “inlined” NEXT_PUBLIC variables values before stating the application - this is what i ended up utilising in commercial production

Recommended Method (Workaround)

The best practice so far is to actually run through JS bundle files right before starting the application and manually replacing values of NEXT_PUBLIC variables “inlined” in the code like described in multiple sources already:

Implementation

Prerequisites

Set NEXT_PUBLIC_SENTRY_ENVIRONMENT .env variable to any value you like as placeholder for future replacement. Make sure it’s unique, since that’s whats going to be searched and replaced.

# .env

NEXT_PUBLIC_SENTRY_ENVIRONMENT=NEXT_PUBLIC_SENTRY_ENVIRONMENT

Search and Replace

Add shell script file to the root of your sources, it executes when running the container. It replaces the placeholder value you've set in previous step with the name of your actual staging environment before starting the application.

# replace_public_env_vars_and_start_server.sh

#!/bin/sh

`find . -type f  -exec sed -i "s/NEXT_PUBLIC_SENTRY_ENVIRONMENT/$SENTRY_ENVIRONMENT/g" {} +`

# server.js is created by next build from the standalone output
# https://nextjs.org/docs/pages/api-reference/next-config-js/output
# CMD ["node", "server.js"]
node server.js

Be aware, that in order to successfully run, the script requires write permissions to files and the directory they are in - it must be executed under appropriate role on wherever you're running it.

Build and Run

After building the image - simply point to shell script from the previous step.

I use the official Next.js "with-docker" example file to build and run my applications - the following snippet is the bottom portion of this file with some changes.

# Dockerfile
...

# Make sure it can be executed
RUN ["chmod", "+x", "/app/replace_public_env_vars_and_start_server.sh"]

ENTRYPOINT [ "/app/replace_public_env_vars_and_start_server.sh" ]

Result

In the browser sentry environment is set to different value on each staging server (in this instance - tst)

Conclusion:

The "replace inlined variables" method offers a practical workaround for achieving environment differentiation in your application, but remember, that:

This method involves additional build complexity.
It's a workaround, not an officially supported solution by Next.js.
It may not work if your deploy environments have limitations on executing scripts or assigning roles under which files are written and/or executed.

Please, let me know in the comments if you're using some other solution to this or have any insight on how to make this one better! 😊 Thanks for reading!

Windows Installation won't work due to 'Unexpected 0x00005 Error' - How to Fix

vavilov2212 — Sun, 04 Aug 2024 13:25:05 +0000

Introduction to the problem

When attempting to install windows 10/11 (I tried several distributions including official images) i encountered error “Unexpected 0x00005 error, verify source is available”. Possible causes are:

faulty memory (storage or RAM)
usb installation source filesystem - during installation some fíes may be created that are larger than 4gb - it’s better to use NTFS instead of FAT32

There also might be indication that something’s off, when before the installation begins, selecting the unallocated space on the target storage drive triggers Setup was unable to create a new system partition or locate an existing one.

💡 If you’re flashing the USD drive from windows - make sure you run Rufus or any other program as Administrator - it’s absolutely necessary.

In my case, while installing the Tiny11 build of Windows, the installation failed at 33%. I figured this might be because some files generated during the process were larger than 4GB. On my Mac, I could only format the thumb drive to FAT32 since NTFS is not supported. I stumbled upon another solution: since the storage drive of the target machine is formatted with NTFS, we can boot from it using one of the partitions as the installation source.

Solution

Following guide in this Microsoft support unswear

We shall be using diskpart command line utility. When in boot screen of windows installer press fn+F10 to open the terminal. First format the disk, which you will use to install windows

diskpart
list disk
# list volume
# list partition
select disk 0 # from the output of the command above
clean

If there’s any sort of issues with cleaning the disk, we can check it for corrupt memory slots and fix them. Exit the diskpart by typing exit, then:

chkdsk /f /r

Another way is to use System File Checker

sfc /scannow

💡 Side note
There might be issues involved, that are out of the scope of this article, like it might be defective CPU or RAM, specific BIOS settings or just anything else really. While researching this issue there were many discussions that resolved in faulty hardware - so be aware.

Next, we need to create partition on the target storage drive.

diskpart
list disk
select disk 0 # from the output of the command above
create partition primary size=5000 # without the size argument it'll take all unallocated space
# 5gb is enough for the tiny11 build, official images require more space
format fs=ntfs quick # quick is really quicker
assign # to choose the letter must be followed by letter=H
active
list partition # check that partition exists

💡 On newer machines the disk is required to have GPT style partition in order for the installation to start, but on older machines it has to be MBR and setting it active is crucial in this case. To clarify what your case might be you need to conduct your own research.
diskpart
select disk 0
convert GPT

Next, copy your installation media contents to this new partition we’ve just created

xcopy c: d: /h /i /c /k /e /r /y

Restart the machine and boot from storage device - unplug the USB - it’ll assure the installation screen actually comes from the internal drive.

Following these steps should help resolve the "Unexpected 0x00005 error".

Additional Tips

In BIOS, configure boot options:
• Disable CSM and use legacy boot if needed.
• For Tiny11 builds, disable TPM; for official Windows 11, enable TPM (since it requires it)
• Consider disabling virtualization settings (e.g., Intel Virtualization).

Please add your tips and solutions in the comments to help others who are struggling to resolve these installation errors!

DEV Community: vavilov2212

Deploying a headless commerce app: a Next.js storefront on Vercel and a Keystone GraphQL admin on Google Cloud Run

TL;DR

Table of contents

The architecture, split into three services

What Keystone actually is

Service 1: the storefront (Next.js on Vercel)

Service 2: the admin and GraphQL API (Keystone 6 on Google Cloud Run)

Service 3: the database (Postgres on Neon)

Local development with Docker Compose

The production container (multi-stage Docker build)

CI/CD with GitHub Actions

How a request is served, and what a deploy does

Standing it up from scratch

Neon

Google Cloud Run

Vercel

GitHub Actions secrets

Environment variables

Locking down the public GraphQL endpoint

What I did: access control in the schema

Going further: taking the endpoint off the public internet

Takeaways

Run -> Log -> Distill: a self-improving memory for AI-assisted development

Table of contents

Chat history is not knowledge

Two kinds of memory: a WAL and a post-mortem

The lifecycle at a glance

Case 1: a planned refactor

Phase 0: a plan with a dependency graph

Phase 1: run and log

Prompt 1: execute the plan

Phase 2: compaction

Prompt 2: compact the journal

Case 2: a spontaneous session

Prompt 3: distill a spontaneous session

The loop closes

Don't keep the journal in CLAUDE.md

Limitations

Prior art

Steal it

I added a RAG-powered AI chat to my landing page - and it's 100% free

TL;DR;

Why bother with a chat assistant

How it's wired together

What is Worklog Studio?

Why it needed a real server

What it costs: nothing

Up next

🕵️‍♂️ The Case of the Missing S3 Metadata: A CORS Deep Dive

Table of Contents

This is Part 2 in a small S3 series

Client and Server behave differently

Server-side (✅ works as expected)

Client-side (❌ metadata comes back empty)

Why no Metadata on the Client

How to Fix It with S3 CORS Rules

🚀 Stop Uploading Files to S3 the Wrong Way

Table of Contents

TL;DR

Motivation

Disposition

The Core: server operates entities

Step 1: The Server Side API Route for Uploads

Step 2: A Decoupled Client Side Architecture

The Data Access Layer

The Business Logic Layer

Step 3: Implementing Secure Downloads

A Deeper Look at the Client Side Download

Handling Environment Variables

Where to go from here?

Enforce Module Imports in FSD (using eslint-plugin-import)

Table of Contents

TL;DR

Motivation

Unforeseen Consequences

Enforcing Code Structure

Customising the Rule

Future Exploration

🧠 Master Your Prompt: A Practical Process to Improve AI Interactions

🚨 Why Migrate from `@import`?

🔁 The `@use` Syntax

⚙️ Automating with `/etc/ppp/ip-up`

🧼 Optional: Cleaning Up with `/etc/ppp/ip-down`