DEV Community: vavilov2212

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!

SVGs in React (almost everything you need to know)

vavilov2212 — Sun, 21 Apr 2024 04:16:06 +0000

SVG stands for Scalable Vector Graphic. True to its name, SVGs are infinitely scalable because they use XML syntax. This means they're essentially a set of instructions for the browser (or any program that can interpret them) to render the image. Unlike raster images (like JPEGs), SVGs don't have a fixed number of pixels, so they can be scaled to any size without losing quality.

💡 In the pre-JSON era, XML (Extensible Markup Language) was the primary way to store and transmit data on the web. It provides a set of rules for encoding and reconstructing various data formats. Interestingly, both HTML and SVG use XML syntax with tags and attributes. You can even style SVG elements with CSS just like you would style regular HTML elements!

Real-world Scenario: Rendering SVGs in React

Let's explore different ways to render SVGs in your React projects.

💡 Code mentioned in this article, can be found in this repository
GitHub - vavilov2212/render-svg-example

Rendering SVGs as Image Tags

One approach is to treat SVGs as external resources. This way, you don't need any additional configuration, and you still benefit from SVG's scalability. Simply import the path to your SVG file and use it as the src attribute of an img tag (the file must be publicly accessible).

import React, { Component } from "react";
import Logo from "../public/logo.svg";

import "./styles.css";

class App extends Component {
  render() {
    return (
      <div>
        <h1> Hello, World! </h1>
        <img src="logo.svg" className="svg" alt="My SVG Image" />
      </div>
    );
  }
}

export default App;

Important Note: In this approach, only attributes applicable to the img tag itself will have any effect. You won't be able to directly style the underlying SVG elements within the image.

Rendering SVGs "as is" in React

Imagine you want your React components to be fully built and ready to render at initial page load, without waiting for external images to download. While simply including the SVG code within your component's markup might seem like an option, it's inefficient. We want to store static resources like SVGs separately from our JavaScript code.

However, there's a catch. When you try to import an SVG file into your component, JavaScript module resolution expects valid JavaScript code, but SVGs are written in XML. Here's where build tools like Webpack come in to help!

💡 For deeper insights of what’s going to happen further, i recommend watching this 10 min video Tech Talk: RegEx (SVG) & JSX: Adapting Vector Graphics for React. In my dev practice, i’ve done exactly this a couple of times before switching to webpack automation.

Webpack to the rescue!

Webpack can be configured to preprocess SVGs during the build process, transforming them into React components that you can easily use within your application. To achieve this, we'll leverage a package called @svgr/webpack.

Let’s edit webpack.config file to automatically transform svg into react component during build time. Install @svgr/webpack and follow usage guide.

// webpack.config.js

module: {
  rules: [
    {
      test: /\.svg$/i,
      issuer: /\.[jt]sx?$/,
      resourceQuery: { not: [/url/] }, // exclude react component if *.svg?url
      use: ["@svgr/webpack"],
    },
  ]
}

Explanation:

test: /\.svg$/i: This line tells Webpack to identify files ending with the .svg extension (case-insensitive).
issuer: /\.[jt]sx?$/: This line ensures the rule applies only when the SVG is imported within a JavaScript or TypeScript file (.js, .jsx, .ts, or .tsx).
resourceQuery: { not: [/url/] }: This line excludes SVGs used with the url() loader (used for embedding small SVGs directly in CSS).
use: ["@svgr/webpack"]: This line specifies the @svgr/webpack loader to handle SVG processing.

Using SVG Components:

Once Webpack processes your SVGs, you can import and use them as React components:

// src/App.js

import Logo from "path/to/logo.svg";
import "path/to/styles.css";

...

return (
  ...
  <Logo className="svg" />
  ...
)

Styling SVG Components:

By transforming SVGs into React components using SVGR, you gain the ability to style the underlying SVG elements directly within your CSS.

// styles.css

.svg ellipse {
  stroke: red;
}

This CSS code will target all ellipse elements within the Logo component you imported, making their stroke red.

As you can see, SVGR processed our import making it possible to simple call it as function and pass props to it.

SVG optimisation with SVGR (utilising SVGO)

SVGR package uses SVGO to optimise SVG code before transforming it into react component. Utilising this may help you to dramatically reduce bundle size.

Refer to the configuration docs for available options or use both packages separately.

SVGs as Data URLs

This technique allows to store SVGs as strings using Data URL scheme, for example:

.some-div {
  background: url("data:image/svg+xml,<svg-string>");
}

Refer to this helpful article Rendering SVGs as images directly in React

Advanced Topics. SVG Sprites

SVG sprites are a technique for combining multiple SVGs into a single image file. This can improve performance by reducing the number of HTTP requests needed to render multiple SVGs on a page. However, managing complex SVG sprites can become cumbersome.

Refer to this helpful article: Complete guide to SVG sprites

With webpack we can use svg-sprite-loader and it can be used in conjunction with other loaders like so:

// webpack.config.js v.4
const path = require("path");

module: {
  rules: [
    {
      test: /\\.svg$/,
      include: path.resolve(__dirname, "src"),
      loaders: [
        `svg-sprite-loader?${JSON.stringify({
          name: "[name].[hash]",
          prefixize: true,
        })}`,
        `svgo-loader?${JSON.stringify({
          plugins: [
            { removeTitle: true },
            { convertPathData: false },
            { removeUselessStrokeAndFill: true },
          ],
        })}`,
      ],
    },
 ]
}

Further Resources:

SVGOMG - Online tool for optimizing SVGs
SVG Path Visualizer - Tool to visualize and understand SVG paths

Conclusion

By understanding the different approaches to using SVGs in React and leveraging tools like SVGR and Webpack, you can effectively integrate scalable vector graphics into your React applications. This guide has equipped you with the knowledge to:

Render SVGs as images or React components
Style SVG elements directly within your components
Optimize SVGs for better performance
Consider best practices and explore advanced techniques

I hope this guide empowers you to create visually appealing and performant React applications using SVGs!

DEV Community: vavilov2212

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

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

📄 The Original Prompt

🎥 Source

🌤️ Strong Design (for reference)

‼️ Flaws and How to Enhance

1. ⚡️ Assumes intent is always worth preserving

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

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

4. ⚡️ No resolution strategy for conflicting criteria

🛠️ Enhanced Prompt

🚀 Would You Trust This?

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

TL;DR: Sass Migration in a Nutshell

🚨 Why Migrate from @import?

🔁 The @use Syntax

✅ Before

✅ After

🧭 Resolving Sass Paths in Next.js

❗includePaths Is a Legacy Pattern

🧩 Better Path Resolution Options

✅ 1. Use Relative Paths (Recommended)

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

🚨 Why Migrate from `@import`?

🔁 The `@use` Syntax

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

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