Instead of manually editing every page, modern JavaScript libraries let you add page numbers directly inside the browser.

In this tutorial, you'll build a browser-based PDF page numbering tool using JavaScript.

Users will be able to upload a PDF, choose where page numbers appear, customize formatting options, preview the document, and download the updated PDF without uploading files to a server.

Everything runs locally inside the browser for better privacy and faster processing.

Table of Contents

1. How PDF Page Numbering Works

2. Project Setup

3. What Library Are We Using?

4. Creating the Upload Interface

5. Reading PDF Pages

6. Previewing Uploaded Pages

7. Selecting Page Number Position

8. Choosing Pages to Number

9. Configuring Number Format and Style

10. Generating the Updated PDF

11. Previewing and Downloading the Final PDF

12. How PDF Page Numbers Help in Real-World Documents

13. Demo: How the PDF Page Number Tool Works

14. Important Notes from Real-World Use

15. Common Mistakes to Avoid

16. Conclusion

How PDF Page Numbering Works

A PDF page numbering tool loads an existing PDF document, modifies selected pages, and inserts page numbers before generating a new downloadable file.

Page numbering is commonly used in reports, contracts, invoices, legal documents, eBooks, manuals, and academic papers where readers need an easy way to navigate through multiple pages.

Without page numbers, it can be difficult to reference specific sections or locate information inside larger documents.

The browser reads the uploaded PDF, processes each page, applies numbering rules, and exports the updated document.

Everything happens locally inside the browser.

This means documents never leave the user's device, improving privacy and security.

In this tutorial, we'll build a tool that allows users to upload a PDF, choose where page numbers appear, customize formatting options, preview the result, and download the updated document directly from the browser.

Project Setup

This project is intentionally simple.

You only need an HTML file, a JavaScript file, and a PDF processing library.

No backend server or database is required.

What Library Are We Using?

We'll use PDF-lib because it allows us to load, modify, and export PDF documents directly inside JavaScript.

Add it using a CDN:

<script src="https://unpkg.com/pdf-lib"></script>

Once loaded, we can read PDF pages and add numbering information directly inside the browser.

Creating the Upload Interface

Users first need a way to upload PDF files.

A simple file input works:

<input type="file" id="pdfFile" accept=".pdf">

After selecting a file, JavaScript can process the PDF and display a preview.

Reading PDF Pages

After the file is uploaded, the PDF must be loaded into memory.

For example:

const bytes = await file.arrayBuffer();

const pdfDoc = await PDFLib.PDFDocument.load(bytes);

const pages = pdfDoc.getPages();

This gives us access to every page inside the document.

Previewing Uploaded Pages

Before applying page numbers, users can preview document pages directly inside the browser.

Showing page previews helps users verify the document before making changes.

The preview section updates automatically after the PDF is uploaded.

Selecting Page Number Position

Different documents require different page number placements.

Some users prefer numbers at the bottom center, while others may use corners or top positions.

The tool provides multiple positioning options.

For example:

page.drawText(pageNumber, {
  x: 250,
  y: 20
});

This allows page numbers to be placed at different coordinates.

Choosing Pages to Number

Not every page needs numbering.

Some users may want numbering applied to all pages. Others may choose a custom range or skip the first page.

The tool supports all of these options.

Configuring Number Format and Style

Users can customize how page numbers appear inside the document.

The numbering format can use standard numbers, lowercase letters, or uppercase letters.

For example:

const pageNumber = `${index + 1}`;

Different numbering styles can also be generated dynamically.

Users can also select different fonts.

The tool allows changing text size, color, and appearance.

Users can also customize numbering patterns.

For example:

• Page 1

• Page 1 of 20

• Custom patterns

Margin settings control spacing between the page number and document edges.

Generating the Updated PDF

Once configuration is complete, users can generate the updated document.

For example:

const pdfBytes = await pdfDoc.save();

The browser processes the pages and inserts numbering automatically.

Previewing and Downloading the Final PDF

After processing, the updated PDF is displayed inside a preview area.

Users can review the results before downloading.

The interface also shows document details such as total pages and file size.

Navigation buttons allow users to browse through pages directly inside the browser.

Finally, the completed PDF can be downloaded.

How PDF Page Numbers Help in Real-World Documents

Page numbers may seem like a small detail, but they become extremely important as documents grow larger.

In business reports, page numbers help readers quickly locate specific sections during meetings, reviews, or presentations. Instead of scrolling through dozens of pages, someone can simply jump to the referenced page number.

Contracts and legal documents also rely heavily on page numbering. When discussing terms or clauses, it's common to reference a specific page to avoid confusion and ensure everyone is looking at the same information.

Academic papers, research documents, and project reports often require page numbers for citations, references, and formatting guidelines. Many institutions consider page numbering a standard requirement for professional submissions.

Page numbers are also useful for manuals, ebooks, user guides, and training materials. Readers can easily return to a previous section or follow instructions that reference another page within the document.

For example, a company handbook might contain 50 or more pages. Without page numbers, employees would need to manually search for information. With numbering applied, sections can simply reference pages such as "See page 24 for leave policy details."

Similarly, invoices, proposals, and financial reports often use formats like "Page 3 of 12" so readers immediately understand how many pages are included in the document.

Adding page numbers improves navigation, organization, professionalism, and overall readability, making documents easier to use for both creators and readers.

Demo: How the PDF Page Number Tool Works

Step 1: Upload a PDF

Users upload a PDF document into the browser.

Step 2: Review Page Previews

The uploaded document pages appear inside the preview section.

Step 3: Configure Page Number Settings

Users choose position, page range, numbering style, font appearance, transparency, and formatting options.

Step 4: Generate the PDF

After configuration is complete, users click the generate button.

Step 5: Review and Download

The finished PDF appears in the preview area.

Users can browse pages, review numbering, rename, and download the updated document.

Important Notes from Real-World Use

When working with large PDF files, performance and memory usage become important considerations.

Documents containing hundreds of pages may take longer to process inside the browser.

A simple validation check can help prevent unsupported files from being processed:

if (!file || file.type !== "application/pdf") {
  alert("Please upload a valid PDF file");
  return;
}

This ensures users upload a PDF before processing begins.

Another useful optimization is limiting very large files before loading them:

const MAX_SIZE = 20 * 1024 * 1024;

if (file.size > MAX_SIZE) {
  alert("PDF file is too large");
  return;
}

This prevents excessive memory usage and improves browser performance.

When generating page numbers, it's also helpful to process pages only once:

const pages = pdfDoc.getPages();

pages.forEach((page, index) => {
  page.drawText(`${index + 1}`);
});

This keeps the numbering process efficient even for larger documents.

Before downloading the final file, always preview the generated document.

Reviewing the output helps verify that page numbers appear in the correct position, use the expected format, and don't overlap important document content.

Common Mistakes to Avoid

One common mistake is hardcoding page number positions.

Different PDF documents can have different page sizes, so fixed coordinates may place page numbers in the wrong location.

For example:

page.drawText(pageNumber, {
  x: 250,
  y: 20
});

Instead, it's usually better to calculate positions dynamically based on the page dimensions.

Another mistake is applying numbering to every page when only a subset of pages should be updated.

For example, users may want to skip the cover page or number only specific page ranges.

Always verify page selection settings before generating the final file.

It's also important to preview the output before downloading.

For example:

const previewPage = pdfDoc.getPage(0);

renderPreview(previewPage);

This helps ensure page numbers appear exactly where expected.

Another common issue is failing to validate uploaded files before processing:

if (!file || file.type !== "application/pdf") {
  alert("Please upload a valid PDF file");
  return;
}

Adding basic validation helps prevent errors and improves the overall user experience.

Conclusion

In this tutorial, you built a browser-based PDF page numbering tool using JavaScript.

You learned how to upload PDF files, preview pages, choose numbering positions, customize formatting options, and generate downloadable PDFs directly inside the browser.

More importantly, you saw how modern browsers can handle document editing tasks locally without relying on a backend server.

This approach keeps the tool fast, private, and easy to use.

If you'd like to try a production-ready version, you can use the AllInOneTools - PDF Page Number Tool.

Once you understand this workflow, you can extend it further with features like headers, footers, watermarks, PDF stamps, document annotations, or advanced page management.

And that's where things start getting really interesting.

Instead of re-creating the document manually, users usually just need a quick way to rotate pages and save the corrected version.

Modern browsers make this possible directly with JavaScript.

In this tutorial, you’ll build a browser-based PDF rotator using JavaScript.

The tool will allow users to upload PDF files, preview pages, rotate selected pages, change orientation, generate an updated PDF, preview the final result, rename the file, and download everything directly from the browser.

Everything works entirely client-side without a backend server.

Table of Contents

1. How PDF Rotation Works

2. Project Setup

3. What Library Are We Using?

4. Creating the Upload Interface

5. Previewing Uploaded PDF Pages

6. Selecting Pages to Rotate

7. Applying Rotation Options

8. Generating the Rotated PDF

9. Previewing and Downloading the Final PDF

10. Why PDF Rotation Is Useful in Real-World Documents

11. Demo: How the PDF Rotator Tool Works

12. Important Notes from Real-World Use

13. Common Mistakes to Avoid

14. Conclusion

How PDF Rotation Works

PDF rotation works by updating the orientation data of PDF pages.

Instead of modifying the actual content manually, JavaScript libraries can rotate pages programmatically and export an updated version of the document.

The browser loads the PDF file, reads page information, applies rotation values like 90°, 180°, or landscape orientation, and then generates a new downloadable PDF.

Everything happens directly inside the browser.

This keeps the process fast, private, and easy to use without uploading files to external servers.

Project Setup

This project is intentionally simple.

You only need an HTML file, a JavaScript file, and a PDF processing library.

Everything runs entirely inside the browser using JavaScript. No backend server or database is required.

What Library Are We Using?

We’ll use the PDF-lib library for editing PDF files directly in the browser.

Add it using a CDN:

<script src="https://unpkg.com/pdf-lib/dist/pdf-lib.min.js"></script>

This library allows us to:

• load PDF documents

• rotate pages

• modify orientation

• export updated PDFs

Creating the Upload Interface

Start with a basic upload input:

<input type="file" id="pdfUpload" accept="application/pdf">

<button onclick="rotatePDF()">
  Rotate PDF
</button>

This allows users to upload PDF files directly from the browser.

Here’s what the upload section looks like inside the tool:

Previewing Uploaded PDF Pages

After uploading a PDF file, users can preview pages directly inside the browser before applying rotations.

The preview section also includes rotation controls so users can rotate pages individually as needed before generating the final PDF.

To render previews, we first load the uploaded PDF document:

const pdfDoc = await PDFLib.PDFDocument.load(arrayBuffer);

const totalPages = pdfDoc.getPageCount();

Next, we render page previews dynamically:

for (let i = 0; i < totalPages; i++) {
  const page = pdfDoc.getPage(i);

  console.log("Rendering page:", i + 1);
}

Users can then move between pages using left and right navigation buttons.

Rotation buttons can also be attached to each preview card:

rotateLeftBtn.addEventListener("click", () => {
  rotatePage(currentPage, -90);
});

rotateRightBtn.addEventListener("click", () => {
  rotatePage(currentPage, 90);
});

This makes it easier to verify page orientation before generating the updated PDF.

Here’s what the page preview section looks like:

Selecting Pages to Rotate

Not every document needs all pages rotated.

Some users may only want to rotate even-numbered pages, odd-numbered pages, or specific pages within the document.

The tool allows users to select which pages should receive the rotation changes before generating the final PDF.

For example, users can choose the rotation scope like this:

const selectedMode = document.querySelector(
  'input[name="pageMode"]:checked'
).value;

Specific page ranges can also be supported:

const customPages = document
  .getElementById("customPages")
  .value;

This gives users more control over which document pages are modified.

Here’s how the page selection controls look inside the tool:

Applying Rotation Options

Once the pages are selected, users can apply different rotation actions directly inside the browser.

Pages can be rotated left by 90 degrees, rotated right by 90 degrees, flipped by 180 degrees, or converted into portrait or landscape orientation.

Here’s a simple example using PDF-lib:

const page = pdfDoc.getPage(pageIndex);

page.setRotation(
  PDFLib.degrees(90)
);

To rotate pages left:

page.setRotation(
  PDFLib.degrees(-90)
);

You can also apply orientation presets dynamically:

if (orientation === "landscape") {
  page.setRotation(PDFLib.degrees(90));
}

These controls allow users to fix scanned documents and incorrect page layouts directly inside the browser.

Here’s what the rotation controls look like inside the tool:

Generating the Rotated PDF

After the rotation settings are configured, users can generate the updated PDF directly inside the browser.

The tool processes selected pages, applies rotation changes, and exports a new downloadable PDF file instantly.

For example:

const pdfBytes = await pdfDoc.save();

Next, create a downloadable file:

const blob = new Blob(
  [pdfBytes],
  { type: "application/pdf" }
);

const url = URL.createObjectURL(blob);

Finally, trigger the download:

const link = document.createElement("a");

link.href = url;
link.download = "rotated-document.pdf";

link.click();

This entire workflow runs locally inside the browser without requiring a backend server.

Here’s what the generate button looks like inside the tool:

Previewing and Downloading the Final PDF

Once processing is complete, the tool displays a live preview of the rotated document.

Users can review updated pages before downloading the final file.

The interface also shows additional document details such as total pages and file size.

A rename option is available before downloading the generated PDF.

For example, users can rename the file like this:

const fileName = prompt(
  "Enter PDF name:",
  "rotated-document"
);

The preview section also includes left and right navigation controls so users can browse through rotated pages directly inside the browser.

Document details can also be displayed dynamically:

fileSizeElement.textContent =
  formatFileSize(blob.size);

pageCountElement.textContent =
  pdfDoc.getPageCount();

This improves usability and helps users verify the final output before downloading.

Here’s what the final output section looks like:

Why PDF Rotation Is Useful in Real-World Documents

PDF rotation may seem like a small feature, but it solves a very common problem in everyday document handling.

Many scanned documents, mobile scans, invoices, certificates, and office files are saved with incorrect orientation. Some pages appear sideways, upside down, or mixed between portrait and landscape layouts.

Instead of reopening and rescanning those files, users can quickly fix page orientation directly inside the browser.

For example, PDF rotation is commonly used for:

• scanned agreements

• invoices and bills

• government forms

• academic documents

• construction drawings

• landscape reports

• mobile camera scans

This becomes especially useful when working with multi-page PDFs where only certain pages need correction.

Some users may only want to rotate:

• even-numbered pages

• odd-numbered pages

• specific pages

• landscape pages only

That’s why page-based rotation controls are important in modern PDF tools.

Browser-based PDF rotation also improves privacy because uploaded documents stay on the user’s device instead of being sent to external servers.

Demo: How the PDF Rotator Tool Works

Step 1: Upload the PDF

Users first upload a PDF document directly into the browser-based tool.

The upload section supports drag-and-drop along with manual file selection.

Here’s what the upload interface looks like:

Step 2: Preview PDF Pages

After uploading the document, the tool generates page previews automatically.

The preview section also includes a rotation option so users can rotate document pages as per required.

Here’s the preview section inside the tool:

Step 3: Configure Rotation Settings

Users can now choose how the PDF pages should rotate.

The tool supports:

• rotate left

• rotate right

• flip 180 degrees

• portrait orientation

• landscape orientation

Users can also choose whether rotations apply to all pages or just certain pages.

Here’s what the rotation settings panel looks like:

Step 4: Generate the Rotated PDF

Once everything is configured, users click the generate button to apply the rotations.

The browser processes the document locally and creates the updated PDF instantly.

Here’s the generate button inside the tool:

Step 5: Preview the Final Output

After processing is complete, the tool displays the rotated PDF preview directly inside the browser.

Users can navigate page-by-page using the left and right controls to verify the final output.

The interface also shows:

• total pages

• file size

• output filename

Here’s the final preview section:

Step 6: Rename and Download the PDF

Before downloading, users can rename the generated PDF file directly inside the browser.

Once renamed, the updated document can be downloaded instantly.

Here’s the rename and download section:

Important Notes from Real-World Use

When working with scanned PDFs, page orientation issues are very common.

Some documents may contain mixed orientations where certain pages are portrait while others are landscape.

Applying rotation changes page-by-page usually gives better results than rotating the entire document blindly.

Large PDF files can also increase processing time inside the browser.

For example:

if (file.size > 50 * 1024 * 1024) {
  alert("Large PDF files may process slowly.");
}

Another useful optimization is previewing pages before applying permanent changes.

This helps users verify page orientation and reduces mistakes before downloading the updated document.

Since everything runs locally in the browser, uploaded documents never leave the user’s device, which improves privacy and security.

Common Mistakes to Avoid

One common mistake is rotating pages multiple times accidentally.

For example, applying two consecutive 90-degree rotations may result in unexpected orientation changes.

Another issue is ignoring page selection before applying rotations.

Users may accidentally rotate all pages instead of specific sections of the document.

Large scanned PDFs can also slow down rendering and preview generation.

Validating uploaded files before processing helps avoid broken workflows:

if (!file || file.type !== "application/pdf") {
  alert("Please upload a valid PDF file.");
  return;
}

Incorrect preview synchronization is another common issue.

If page previews aren't refreshed after rotation, users may think the rotation failed even though the exported PDF is correct.

Updating previews dynamically after each rotation improves the overall experience.

Conclusion

In this tutorial, you built a browser-based PDF rotator using JavaScript.

You learned how to upload PDF files, preview document pages, rotate selected pages, change page orientation, generate updated PDFs, and download the final document directly inside the browser.

More importantly, you saw how modern browsers can handle practical PDF editing tasks locally without relying on a backend server.

This approach keeps the tool fast, private, and easy to use.

You can also try the live tool here: AllInOneTools - PDF Rotator Tool.

Once you understand this workflow, you can extend it further with features like PDF page extraction, annotations, document organization, digital signatures, or advanced editing tools.

And that’s where things start getting really interesting.

Whether it’s adding a company logo, a “CONFIDENTIAL” label, or a draft watermark, users often need a quick way to modify PDFs without uploading files to external servers.

Modern browsers make this much easier than before. Instead of sending documents to a backend, we can process PDF files directly inside the browser using JavaScript. This keeps documents private while making the tool fast and easy to use.

In this tutorial, you’ll build a browser-based PDF watermark tool using JavaScript.

The tool will support both text and image watermarks, adjustable opacity, rotation, page selection, positioning controls, and downloadable PDF output directly from the browser.

Everything works entirely client-side without any backend.

Table of Contents

1. How PDF Watermarking Works

2. Project Setup

3. What Library Are We Using?

4. Creating the Upload Interface

5. Adding Text Watermarks

6. Adding Image Watermarks

7. Positioning and Opacity Controls

8. Selecting Pages to Apply

9. Generating and Downloading the Final PDF

10. Demo: How the PDF Watermark Tool Works

11. Important Notes from Real-World Use

12. Common Mistakes to Avoid

13. Conclusion

How PDF Watermarking Works

A PDF watermark is simply additional text or an image layered on top of an existing PDF page.

In the browser, JavaScript libraries can load PDF pages, modify them visually, and export a new downloadable version.

The process starts when the user uploads a PDF file into the tool. JavaScript then reads the document, loads each page, and applies watermark elements like text or logos on top of the existing content. After positioning and opacity settings are applied, the updated PDF is generated and downloaded directly from the browser.

Everything happens locally inside the browser. This means uploaded documents never leave the user’s device, which improves privacy and security.

Project Setup

This project is intentionally simple. Everything runs directly inside the browser using JavaScript, so no backend server is required.

You only need:

• an HTML file

• a JavaScript file

• a PDF processing library

What Library Are We Using?

We’ll use the PDF-lib library for editing existing PDF documents inside the browser.

Add it using a CDN:

<script src="https://unpkg.com/pdf-lib/dist/pdf-lib.min.js"></script>

This library allows us to load PDF files directly in the browser, modify existing pages, insert custom text or image watermarks, and finally export the updated document as a new downloadable PDF.

Because everything runs client-side with JavaScript, users can edit PDFs without uploading files to a server.

How to Create the Upload Interface

Start with a basic upload input:

<input type="file" id="pdfUpload" accept="application/pdf">

<button onclick="addWatermark()">
  Apply Watermark
</button>

This allows users to upload PDF files directly from the browser.

The tool also includes watermark settings like text input, image upload, opacity controls, positioning, and page selection.

Here’s what the watermark settings panel looks like inside the tool:

How to Add Text Watermarks

Text watermarks are commonly used for labels like “CONFIDENTIAL”, “DRAFT”, or “APPROVED”.

For example:

page.drawText("CONFIDENTIAL", {
  x: 200,
  y: 300,
  size: 48,
  opacity: 0.5
});

This inserts watermark text directly onto the PDF page. Users can also customize the appearance of the watermark directly inside the tool.

For text watermarks, users can adjust the font size, change the text color, apply bold or italic styling, control opacity levels, and rotate the watermark at different angles for better visibility and protection.

Here’s an example of text watermark controls inside the tool:

How to Add Image Watermarks

Some users may want to apply logos or branded graphics instead of plain text.

For example:

const image = await pdfDoc.embedPng(imageBytes);

page.drawImage(image, {
  x: 180,
  y: 250,
  width: 120,
  height: 120,
  opacity: 0.5
});

This inserts an image watermark onto the PDF page.

The tool also supports image scaling controls so users can resize uploaded logos before applying them.

Here’s an example of image watermark settings inside the tool:

Positioning and Opacity Controls

Watermark placement is important for readability and document appearance.

Users may want centered watermarks, corner positioning, or diagonal overlays depending on the document type.

For example:

page.drawText("CONFIDENTIAL", {
  x: 220,
  y: 250,
  rotate: degrees(45),
  opacity: 0.5
});

This creates a rotated semi-transparent watermark.

The tool also allows users to adjust watermark positioning and appearance directly inside the browser.

Users can control the X and Y position, change opacity levels, rotate the watermark at different angles, and quickly move the watermark using directional placement controls.

This makes it easier to place watermarks correctly without manually editing the PDF in external software.

Here’s an example of positioning controls inside the tool:

How to Select Pages to Apply

Not every watermark needs to appear on every page. Some users may only want watermarks on specific pages.

For example:

const selectedPages = [1, 3, 5];

The tool allows users to control exactly where the watermark should appear.

For example, a watermark can be applied to every page in the document, only even-numbered pages, only odd-numbered pages, or specific custom page ranges like 1-3,5.

This makes the tool more flexible for real-world use cases such as contracts, invoices, reports, certificates, and branded documents..

Here’s an example of page selection options inside the tool:

How to Generate and Download the Final PDF

Once watermark settings are configured, the browser generates the updated PDF directly inside the browser.

For example:

const pdfBytes = await pdfDoc.save();

Then the updated file becomes downloadable:

download(pdfBytes, "watermarked.pdf");

This process happens locally without uploading files to external servers.

Demo: How the PDF Watermark Tool Works

For this example, we’ll apply a custom watermark directly inside the browser.

Step 1: Upload the PDF

Users upload a PDF document into the watermark tool.

Step 2: Preview the Uploaded PDF

After uploading the PDF, the tool generates a live preview directly inside the browser.

Users can navigate through pages using the left and right arrow buttons to review the document before applying the watermark.

This page-by-page preview helps users verify the correct file, check page content, and decide where the watermark should appear.

Here’s how the PDF preview section looks inside the tool:

Step 3: Configure Watermark Settings

Users can choose between text or image watermark mode.

For text watermarks, users can customize font size, color, opacity, and rotation.

For image watermarks, users can upload a logo and adjust image scale before applying it.

Step 4: Position and Apply the Watermark

Users can reposition the watermark visually before generating the final file.

The tool also allows users to control where the watermark should be applied within the document. For example, the watermark can appear on all pages, only even-numbered pages, only odd-numbered pages, or specific custom page ranges.

Opacity and rotation controls help improve visibility without blocking important document content.

This gives users more flexibility when watermarking contracts, invoices, reports, certificates, or branded PDFs.

Step 5: Generate the Watermarked PDF

Once the watermark settings are configured, users can click the generate button to process the document directly inside the browser.

The tool applies the watermark to the selected pages and prepares the updated PDF instantly.

Here’s how the generate PDF button looks inside the tool:

Step 6: Preview and Download the Updated PDF

After processing is complete, the tool displays a live preview of the final watermarked PDF.

Users can review the updated document before downloading it. The interface also shows useful file details such as total pages and final file size.

A rename option is available before downloading the generated PDF.

Here’s an example of the final output preview section:

Important Notes from Real-World Use

When working with large PDF documents, performance and rendering speed become important.

Applying watermarks page-by-page is usually more stable than modifying everything simultaneously.

For example:

for (const page of pdfDoc.getPages()) {
  // apply watermark
}

Another useful optimization is lowering image watermark size before embedding large logos. This reduces output file size and improves processing speed.

Opacity is also important. Very dark watermarks can make documents difficult to read, especially on printed pages. Keeping watermark opacity between 0.3 and 0.5 usually works well in real-world situations.

Since everything runs locally inside the browser, uploaded documents remain private and never leave the user’s device.

Common Mistakes to Avoid

One common mistake is applying watermarks at full opacity. This can make the document difficult to read.

For example:

opacity: 1

Instead, use lower opacity values:

opacity: 0.4

Another issue is incorrect watermark positioning. If coordinates are hardcoded incorrectly, the watermark may appear outside the visible page area.

Dynamic positioning usually works better across different page sizes. Large image watermarks can also increase PDF file size significantly. Resizing images before embedding them helps improve performance.

Another common mistake is forgetting to validate uploaded files:

if (!file || file.type !== "application/pdf") {
  alert("Please upload a valid PDF file.");
  return;
}

This prevents unsupported files from breaking the tool.

Conclusion

In this tutorial, you built a browser-based PDF watermark tool using JavaScript.

You learned how to upload PDF files, apply text or image watermarks, control positioning and opacity, and generate downloadable PDFs directly inside the browser.

More importantly, you saw how modern browsers can handle document editing tasks locally without relying on a backend server.

This approach keeps the tool fast, private, and easy to use.

You can also try the live tool here: All In One Tools PDF Watermark Tool

Once you understand this workflow, you can extend it further with features like digital signatures, PDF annotations, stamping tools, password protection, or advanced document editing.

And that’s where things start getting really interesting.

Modern browsers make this much easier than before.

Instead of uploading documents to a server, we can process PDF files directly inside the browser using JavaScript. This keeps the tool fast, private, and easy to use.

In this tutorial, you’ll build a browser-based PDF to image converter using JavaScript.

The tool will support uploading PDF files, previewing pages, selecting image formats like JPG or PNG, adjusting image quality, and downloading converted images directly from the browser.

Everything runs entirely client-side without any backend.

Table of Contents

1. How PDF to Image Conversion Works

2. Project Setup

3. What Library Are We Using?

4. Creating the Upload Interface

5. Reading the PDF File

6. Rendering PDF Pages as Images

7. Selecting Image Format and Quality

8. Generating and Downloading Images

9. Demo: How the PDF to Image Tool Works

10. Important Notes from Real-World Use

11. Common Mistakes to Avoid

12. Conclusion

How PDF to Image Conversion Works

A browser can't directly convert PDF files into images on its own.

Instead, JavaScript libraries render PDF pages onto an HTML canvas, which can then be exported as image files like JPG or PNG.

The process starts when users upload a PDF document into the browser. JavaScript then reads the file, renders each PDF page visually onto a canvas, converts those rendered pages into image files, and finally makes them available for download.

Everything happens locally inside the browser.

This means users don't need to upload private documents to external servers, making the process faster and more privacy-friendly.

Project Setup

This project is intentionally simple. Everything runs directly inside the browser using JavaScript, so no backend or server setup is required.

You only need:

• an HTML file

• a JavaScript file

• the PDF.js library

What Library Are We Using?

We’ll use Mozilla’s PDF.js library to render PDF pages inside the browser.

Add it using a CDN:

<script src="https://cdnjs.cloudflare.com/ajax/libs/pdf.js/3.11.174/pdf.min.js"></script>

Once loaded, the browser can read and render PDF pages directly using JavaScript.

Creating the Upload Interface

Start with a simple upload area:

<input type="file" id="pdfUpload" accept="application/pdf">

<select id="format">
  <option>JPG</option>
  <option>PNG</option>
  <option>WEBP</option>
</select>

<input type="range" id="quality" min="10" max="100" value="90">

<button onclick="convertPDF()">
  Convert to Images
</button>

This allows users to upload PDF files directly into the browser.

Here’s what the upload section looks like inside the tool:

Reading the PDF File

After the file is uploaded, we need to read it using JavaScript.

For example:

const file = document.getElementById("pdfUpload").files[0];

const reader = new FileReader();

reader.onload = async function () {
  const typedArray = new Uint8Array(reader.result);

  const pdf = await pdfjsLib.getDocument(typedArray).promise;

  console.log(pdf.numPages);
};

reader.readAsArrayBuffer(file);

This loads the PDF document directly inside the browser.

You can then access each page individually.

Rendering PDF Pages as Images

Once the PDF is loaded, pages can be rendered onto a canvas.

For example:

const page = await pdf.getPage(1);

const viewport = page.getViewport({ scale: 2 });

const canvas = document.createElement("canvas");

const context = canvas.getContext("2d");

canvas.width = viewport.width;
canvas.height = viewport.height;

await page.render({
  canvasContext: context,
  viewport: viewport
}).promise;

This renders the selected PDF page visually inside the browser.

After rendering, the canvas can be converted into an image.

For example:

const imageData = canvas.toDataURL("image/jpeg", 0.9);

This creates a downloadable image version of the PDF page.

Selecting Image Format and Quality

Before generating the final images, users may want to customize output settings.

Different image formats work better for different situations.

For example:

• JPG works well for smaller file sizes

• PNG preserves better quality

• WEBP offers modern compression

Users can also control image quality using a slider.

For example:

canvas.toDataURL("image/jpeg", 0.8);

The value 0.8 controls compression quality.

Here’s an example of image format and quality settings inside the tool:

Generating and Downloading Images

Once pages are rendered, images can be downloaded directly from the browser.

For example:

const link = document.createElement("a");

link.href = imageData;

link.download = `page-${pageNumber}.jpg`;

link.click();

This downloads the generated image instantly.

When working with multi-page PDFs, the same process can run for every page automatically.

This allows users to export complete PDF documents as separate image files.

Demo: How the PDF to Image Tool Works

For this example, we’ll convert PDF pages into downloadable image files directly inside the browser.

Step 1: Upload PDF Files

Users upload one or more PDF files into the converter.

Step 2: Preview Uploaded Pages

The tool generates page previews before conversion.

This helps users verify the uploaded document visually.

Step 3: Configure Output Settings

Users can choose image format and quality settings before generating images.

This allows better control over output size and image clarity.

Step 4: Convert PDF Pages into Images

Once settings are configured, users click the convert button.

The browser processes the PDF locally and generates image files instantly.

Step 5: Download Generated Images

After conversion, every PDF page becomes a downloadable image.

Important Notes from Real-World Use

When working with large PDFs, performance and memory usage become important.

Documents with many pages can slow down rendering if everything is processed at once.

One practical optimization is processing pages step-by-step instead of rendering the entire document immediately.

For example:

for (let i = 1; i <= pdf.numPages; i++) {
  const page = await pdf.getPage(i);

  // render page
}

This keeps browser memory usage more stable.

Another useful optimization is reducing render scale for large documents.

For example:

const viewport = page.getViewport({
  scale: 1.5
});

Lower scale values generate smaller image files and improve performance.

You can also resize generated images before export.

For example:

canvas.width = viewport.width;
canvas.height = viewport.height;

This helps reduce unnecessary file size growth.

Since everything runs locally inside the browser, uploaded PDF files never leave the user’s device, which improves privacy and security.

Common Mistakes to Avoid

One common mistake is not validating uploaded files before processing them.

For example:

if (!file || file.type !== "application/pdf") {
  alert("Please upload a valid PDF file.");
  return;
}

This prevents unsupported files from breaking the tool.

Another issue is rendering extremely large pages at very high scale values.

Large canvas rendering can consume a lot of memory and slow down conversion significantly.

Using smaller scale values usually improves performance.

Another common mistake is forgetting to wait for page rendering before exporting the image.

For example:

await page.render({
  canvasContext: context,
  viewport: viewport
}).promise;

Without await, the image may export before rendering finishes.

Incorrect file naming can also confuse users when multiple pages are generated.

Adding page numbers to filenames improves organization:

link.download = `page-${pageNumber}.jpg`;

Conclusion

In this tutorial, you built a browser-based PDF to image converter using JavaScript.

You learned how to upload PDF files, render pages inside the browser, generate images, and download them directly without using a backend server.

More importantly, you saw how modern browsers can handle document processing tasks locally while keeping user files private.

This approach keeps the tool fast, lightweight, and easy to use.

Once you understand this workflow, you can extend it further with features like ZIP downloads, batch exports, page selection, watermarking, or image compression.

You can also try a real working version here:

https://allinonetools.net/pdf-to-image-converter/

And that’s where things start getting really interesting.

Modern browsers make this much easier than before.

Instead of uploading files to a server, we can now process images directly in the browser using JavaScript. This keeps the tool fast, private, and easy to use.

In this tutorial, you’ll build a browser-based Image to PDF converter using JavaScript.

The tool will support uploading multiple images, sorting files, choosing orientation and page size, configuring margins, and merging images into either a single PDF or separate PDF files. Users will also be able to preview and download the generated document directly in the browser.

Everything runs entirely client-side without any backend.

Table of Contents

1. How Image to PDF Conversion Works

2. Project Setup

3. What Library Are We Using?

4. Creating the Upload Interface

5. Reading Uploaded Images

6. Generating the PDF

7. Handling Multiple Images

8. Configuring PDF Settings

9. Renaming and Downloading the PDF

10. Demo: How the Image to PDF Tool Works

11. Important Notes from Real-World Use

12. Common Mistakes to Avoid

13. Conclusion

How Image to PDF Conversion Works

The browser can't directly combine images into a PDF by itself.

Instead, we'll use a JavaScript PDF library that creates pages, inserts images, and exports everything as a downloadable PDF document.

The process starts when users upload one or multiple images into the browser. JavaScript then reads the image data and prepares it for PDF generation. After that, the tool creates PDF pages, inserts the uploaded images into those pages, and finally exports everything as a downloadable PDF document.

Everything happens locally inside the browser.

This means users don’t need to upload private files to a server, which makes the process faster and more privacy-friendly.

Project Setup

This project is intentionally simple.

You only need:

• an HTML file

• a JavaScript file

• a PDF library

No backend or database is required.

What Library Are We Using?

We’ll use the jsPDF library. It allows us to generate PDF files directly in JavaScript.

Add it using a CDN:

<script src="https://cdnjs.cloudflare.com/ajax/libs/jspdf/2.5.1/jspdf.umd.min.js"></script>

Once loaded, we can create and export PDF files directly from the browser.

Creating the Upload Interface

Start with a basic upload area:

<input type="file" id="upload" multiple accept="image/*">

<button onclick="convertToPDF()">
  Convert to PDF
</button>

This allows users to upload multiple image files and generate the PDF.

Here’s what the upload section looks like inside the tool:

You can also expand the interface with additional controls for sorting, page settings, margins, and merge modes.

Reading Uploaded Images

After users select files, we need to read them in JavaScript.

We can use FileReader for this:

const fileInput = document.getElementById("upload");

const files = fileInput.files;

for (const file of files) {
  const reader = new FileReader();

  reader.onload = function (e) {
    const imageData = e.target.result;

    console.log(imageData);
  };

  reader.readAsDataURL(file);
}

This converts uploaded images into readable Base64 data that can later be inserted into the PDF.

Generating the PDF

Now we can create the PDF document.

const { jsPDF } = window.jspdf;

const pdf = new jsPDF();

Once the PDF is created, images can be inserted into pages:

pdf.addImage(imageData, "JPEG", 10, 10, 180, 120);

This inserts the uploaded image into the PDF page at a specific position and size.

Finally, export the document:

pdf.save("images.pdf");

This downloads the generated PDF instantly.

Handling Multiple Images

If users upload multiple files, each image can be added to its own PDF page automatically.

For example:

files.forEach((file, index) => {

  if (index !== 0) {
    pdf.addPage();
  }

});

This creates a new page before inserting the next image into the document.

In some situations, users may also want multiple images on the same page instead of one image per page.

For example:

pdf.addImage(img1, "JPEG", 10, 20, 80, 80);

pdf.addImage(img2, "JPEG", 110, 20, 80, 80);

This allows more flexible layouts for galleries, reports, or grouped documents.

Configuring PDF Settings

Before generating the final PDF, users can customize several layout and output settings.

These settings improve document quality and give users more control over the generated file.

Here’s what the configuration panel looks like inside the tool:

Sorting Images

When multiple images are uploaded, organizing them properly becomes important before generating the PDF.

Users may want to sort images alphabetically, reverse the order, or arrange them based on file size.

For example, images can be sorted alphabetically like this:

files.sort((a, b) => a.name.localeCompare(b.name));

You can also sort files by size:

files.sort((a, b) => a.size - b.size);

Here’s an example of sorting options inside the tool:

This helps users organize documents more efficiently before converting them into a PDF.

Choosing Orientation

Different images work better in different page orientations.

Portrait orientation works well for vertical images, while landscape orientation is better for wider images.

For example:

const pdf = new jsPDF({
  orientation: "portrait"
});

You can also switch to "landscape" when needed.

Here’s an example of orientation options inside the tool:

Selecting Page Size

PDF page size controls the dimensions of the generated document.

For example:

const pdf = new jsPDF({
  unit: "mm",
  format: "a4"
});

This creates an A4-sized PDF document using millimeter units.

Other formats like letter, legal, or custom page sizes can also be supported.

Here’s an example of selecting page size options inside the tool:

Adding Margins

Margins create spacing between the image and the edges of the page.

Without margins, images may touch the borders and appear cramped.

For example:

const margin = 10;

pdf.addImage(imageData, "JPEG", margin, margin, 180, 120);

Here’s an example of margins options inside the tool:

This creates cleaner spacing around the inserted image.

Automatic Image Fitting

One common issue when generating PDFs from images is incorrect sizing.

If images are inserted with fixed dimensions, they may stretch, overflow outside the page, or appear distorted.

Instead, it’s better to calculate image dimensions dynamically.

For example:

const pageWidth = pdf.internal.pageSize.getWidth();

const imgWidth = pageWidth - 20;

const imgHeight = (image.height * imgWidth) / image.width;

pdf.addImage(imageData, "JPEG", 10, 10, imgWidth, imgHeight);

This automatically scales images proportionally while maintaining margins and layout consistency.

Merge Options

One useful feature is allowing different output modes.

For example, users may want to merge all uploaded images into a single PDF document when creating reports, notes, or combined files.

In some cases, users may prefer generating separate PDFs for each image instead of combining everything together. This can be useful when exporting individual documents or scanned pages.

Custom grouping is another helpful option because it allows users to combine selected images into multiple PDFs based on their own arrangement or categories.

These different output modes make the tool much more flexible for different real-world use cases.

A simple selection dropdown works well:

<select id="mergeMode">
  <option>Merge all into Single PDF</option>
  <option>Create Separate PDFs</option>
  <option>Custom Grouping</option>
</select>

Once selected, JavaScript can apply different generation logic based on the chosen mode.

Here’s an example of merge mode options inside the tool:

This makes the tool more flexible for handling different document workflows.

Renaming and Downloading the PDF

After generating the document, users may want to rename the file before downloading.

You can prompt for a filename like this:

const fileName = prompt("Enter PDF name:", "images");

pdf.save(`${fileName}.pdf`);

This gives users more control over the exported file.

Here’s an example of the rename popup inside the tool:

Demo: How the Image to PDF Tool Works

Step 1: Upload Images

Users upload one or multiple image files into the browser-based tool.

The tool supports common formats like JPG, PNG, and WEBP.

Step 2: Configure PDF Settings

Users can customize layout settings before generating the PDF.

This includes:

• sorting images

• orientation

• page size

• margins

• merge mode

These settings help create cleaner PDF output.

Step 3: Generate the PDF

Once settings are configured, users click the convert button.

The browser processes all uploaded images locally and generates the PDF instantly.

Step 4: Rename the Generated File

Before downloading, users can rename the generated PDF.

This improves organization when exporting multiple documents.

Step 5: Download the PDF

Finally, the generated PDF becomes available for download directly in the browser.

The entire process works without uploading files to any server.

Important Notes from Real-World Use

When working with large images, performance and memory usage become important.

Large images can slow down PDF generation and create unnecessarily large output files.

For example, you can limit upload size before processing:

const MAX_SIZE = 10 * 1024 * 1024;

if (file.size > MAX_SIZE) {
  alert("Image is too large.");
  return;
}

Another useful optimization is resizing images before inserting them into the PDF.

For example:

const canvas = document.createElement("canvas");

const ctx = canvas.getContext("2d");

canvas.width = image.width * 0.5;
canvas.height = image.height * 0.5;

ctx.drawImage(image, 0, 0, canvas.width, canvas.height);

const resizedImage = canvas.toDataURL("image/jpeg", 0.7);

This reduces image dimensions and compression quality before generating the PDF.

It also helps reduce memory usage and improves PDF generation speed for large files.

Since everything runs directly inside the browser, uploaded images never leave the user’s device, which improves privacy.

Common Mistakes to Avoid

One common mistake is not validating uploaded files before processing them.

For example, users may upload unsupported formats or attempt to generate a PDF without selecting images.

Always validate input before processing:

if (!fileInput.files.length) {
  alert("Please upload images first.");
  return;
}

Another issue is inserting very large images without resizing them first.

Large images can create oversized PDFs and reduce performance significantly.

Incorrect image positioning is also common.

If dimensions are hardcoded incorrectly, images may overflow outside the page or become distorted.

Using dynamic image sizing and margins helps prevent these layout issues.

Conclusion

In this tutorial, you built a browser-based image to PDF converter using JavaScript.

You learned how to upload images, generate PDF documents, configure layout settings, and export files directly inside the browser.

More importantly, you saw how modern browsers can handle document generation locally without relying on a backend server.

This approach keeps the tool fast, private, and easy to use.

Once you understand this workflow, you can extend it further with features like compression, drag-and-drop sorting, watermarking, batch exports, or advanced PDF editing tools.

You can also try a full working version here:

https://allinonetools.net/image-to-pdf-converter/

And that’s where things start getting really interesting.

It doesn't learn.

You ingest 500 documents. You ask a question. The system retrieves the three most similar chunks and hands them to the LLM. Repeat for the next query.

The system knows exactly as much as it did on day one. It's a library that never builds a card catalog, never cross-references its own shelves, never notices that three of its books are saying contradictory things.

That's what I set out to fix with a knowledge reflection layer. After every ingest, the system finds semantically related documents already in the index and asks an LLM to synthesise what's new, how it connects, and what gap remains. That synthesis gets embedded, stored, and boosted in search results.

The knowledge base gets smarter as you add more documents — not just bigger.

This tutorial shows you exactly how to build it.

Table of Contents

1. What You Will Build

2. Prerequisites

3. How to Set Up the Base System

4. Why Standard RAG Has a Memory Problem

5. Step 1: Schema Update

6. Step 2: The Reflection Engine

7. Step 3: Consolidation

8. Step 4: Wire It Into Your Ingest Handler

9. Step 5: Boost Reflections in Search

10. Step 6: Filtering by doc_type

11. What Changes After You Build This

12. Deploying

13. What to Build Next

What You Will Build

In this tutorial, you'll build a post-ingest reflection pipeline that:

1. Fires automatically after every document ingest

2. Finds the most semantically related documents already in the index

3. Asks Kimi K2.5 to synthesise a three-sentence insight linking the new document to existing knowledge

4. Stores that reflection with doc_type=reflection and a 1.5× ranking boost in search results

5. Consolidates reflections into summaries every three ingests

By the end, searching your knowledge base will surface both raw document chunks and reflection artifacts the system wrote on ingest.

Prerequisites

You will need:

• A Cloudflare account — free tier works

• Node.js v18+ and Wrangler CLI installed (npm install -g wrangler)

• Basic TypeScript familiarity

No external API keys. Everything runs on Cloudflare's infrastructure.

How to Set Up the Base System

If you have already built the RAG system from my freeCodeCamp handbook, skip this section — your system is ready for the reflection layer.

If you're starting fresh, this section gets you to a working base in about 15 minutes.

Scaffold the Project

npm create cloudflare@latest rag-reflection-system
cd rag-reflection-system

Choose: Hello World example → TypeScript → No deploy yet.

Create the Vectorize Index and D1 Database

npx wrangler vectorize create rag-index --dimensions=384 --metric=cosine
npx wrangler d1 create rag-db

Configure wrangler.toml

name = "rag-reflection-system"
main = "src/index.ts"
compatibility_date = "2026-01-01"

[[vectorize]]
binding = "VECTORIZE"
index_name = "rag-index"

[[d1_databases]]
binding = "DB"
database_name = "rag-db"
database_id = "YOUR_DB_ID"

[ai]
binding = "AI"

Create the documents Table

-- migrations/001_init.sql
CREATE TABLE IF NOT EXISTS documents (
  id TEXT PRIMARY KEY,
  content TEXT NOT NULL,
  source TEXT,
  date_created TEXT DEFAULT (datetime('now'))
);

npx wrangler d1 execute rag-db --remote --file=./migrations/001_init.sql

Add the ingest and search endpoints

Replace src/index.ts with this minimal working system:

export interface Env {
  VECTORIZE: VectorizeIndex;
  DB: D1Database;
  AI: Ai;
}

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    const url = new URL(request.url);

    if (url.pathname === '/ingest' && request.method === 'POST') {
      const { id, content, source } = await request.json() as any;

      const embResult = await env.AI.run('@cf/baai/bge-small-en-v1.5', {
        text: [content.slice(0, 512)],
      }) as any;
      const vector = embResult.data[0];

      await env.VECTORIZE.upsert([{
        id,
        values: vector,
        metadata: { content: content.slice(0, 1000), source, doc_type: 'raw' },
      }]);

      await env.DB.prepare(
        'INSERT OR REPLACE INTO documents (id, content, source) VALUES (?, ?, ?)'
      ).bind(id, content, source ?? '').run();

      return Response.json({ success: true, id });
    }

    if (url.pathname === '/search' && request.method === 'POST') {
      const { query } = await request.json() as any;

      const embResult = await env.AI.run('@cf/baai/bge-small-en-v1.5', {
        text: [query],
      }) as any;
      const vector = embResult.data[0];

      const results = await env.VECTORIZE.query(vector, {
        topK: 5,
        returnMetadata: 'all',
      });

      const context = results.matches
        .map(m => m.metadata?.content as string)
        .filter(Boolean)
        .join('\n\n');

      const answer = await env.AI.run('@cf/moonshotai/kimi-k2.5', {
        messages: [
          { role: 'system', content: 'Answer using only the context provided.' },
          { role: 'user', content: `Context:\n\({context}\n\nQuestion: \){query}` },
        ],
        max_tokens: 256,
      }) as any;

      return Response.json({ answer: answer.response, sources: results.matches.map(m => m.id) });
    }

    return new Response('RAG system running', { status: 200 });
  },
};

Deploy and Verify

npx wrangler deploy

Test it:

# Ingest a document
curl -X POST https://your-worker.workers.dev/ingest \
  -H "Content-Type: application/json" \
  -d '{"id": "doc-001", "content": "Cursor pagination beats offset pagination for live-updating datasets because offset becomes unreliable when rows are inserted or deleted during pagination."}'

# Search
curl -X POST https://your-worker.workers.dev/search \
  -H "Content-Type: application/json" \
  -d '{"query": "what pagination approach should I use?"}'

If you get a grounded answer back, the base system is working. The next sections add the reflection layer on top of this foundation.

Why Standard RAG Has a Memory Problem

Standard RAG retrieval is stateless. Every query goes in cold. The system has no memory of what it found before, no synthesis of what it learned across documents, and no growing understanding of what questions remain unanswered.

Imagine you've ingested 200 documents about your product. Twelve of them touch on a pricing decision made last year. No single one has the full picture — it's distributed across quarterly reports, meeting notes, an internal Slack export, a few Notion pages.

A user asks: "Why did we change our pricing structure?"

Standard RAG retrieves the three most similar chunks. If those three chunks collectively have the answer, great. If they don't — if the real answer requires synthesising across those twelve documents — the system has no mechanism for that. It returns fragments. The LLM makes its best guess.

The reflection layer addresses this directly. When the twelfth pricing document gets ingested, the system finds the eleven related documents, synthesises what connects them, and stores that synthesis as a retrievable artifact. The answer to "why did we change our pricing structure" exists in the index before anyone asks the question.

Not smarter retrieval — smarter indexing.

Step 1: Schema Update

The reflection layer needs two new fields in your D1 documents table. Run this migration:

-- migrations/003_add_reflection_fields.sql
ALTER TABLE documents ADD COLUMN doc_type TEXT DEFAULT 'raw';
ALTER TABLE documents ADD COLUMN reflection_score REAL DEFAULT 0;
ALTER TABLE documents ADD COLUMN parent_reflection_id TEXT;

Apply it:

wrangler d1 execute mcp-knowledge-db --remote --file=./migrations/003_add_reflection_fields.sql

doc_type distinguishes raw documents (raw), single-document reflections (reflection), and consolidated multi-reflection summaries (summary). You'll use this field to filter — exposing only reflections to users who want the distilled view, or excluding them for users who want raw source chunks.

Step 2: The Reflection Engine

Create src/engines/reflection.ts. This is the core of the layer.

import { Env } from '../types/env';
import { resolveEmbeddingModel, resolveReflectionModel } from '../config/models';

const REFLECTION_BOOST = 1.5;
const CONSOLIDATION_THRESHOLD = 3; // consolidate every N new reflections

export async function reflect(
  newDocId: string,
  newDocContent: string,
  env: Env
): Promise<void> {
  // 1. Find semantically related documents already in the index
  const embModel = resolveEmbeddingModel(env.EMBEDDING_MODEL);
  const embResult = await env.AI.run(embModel.id as any, {
    text: [newDocContent.slice(0, 512)],
  });
  const queryVector = (embResult as any).data?.[0];
  if (!queryVector) return;

  const related = await env.VECTORIZE.query(queryVector, {
    topK: 5,
    filter: { doc_type: { $eq: 'raw' } },
    returnMetadata: 'all',
  });

  const relatedDocs = (related.matches ?? []).filter(
    m => m.id !== newDocId && (m.score ?? 0) > 0.65
  );

  if (relatedDocs.length === 0) return; // nothing related yet — skip

  // 2. Build synthesis prompt
  const relatedSummaries = relatedDocs
    .slice(0, 3)
    .map((m, i) => `Document \({i + 1}: \){String(m.metadata?.content ?? '').slice(0, 300)}`)
    .join('\n\n');

  const prompt = `You are synthesising knowledge across documents in a knowledge base.

New document:
${newDocContent.slice(0, 600)}

Related existing documents:
${relatedSummaries}

Write exactly three sentences:
1. What the new document adds that the existing documents don't already cover
2. How the new document connects to or extends the existing documents
3. What gap or question remains unanswered across all these documents

Be specific. Reference actual content. Do not summarise — synthesise.`;

  // 3. Call the reflection model
  const reflModel = resolveReflectionModel(env.REFLECTION_MODEL);
  const llmResp = await env.AI.run(reflModel.id as any, {
    messages: [{ role: 'user', content: prompt }],
    max_tokens: 180,
  });

  const reflectionText = (llmResp as any)?.response?.trim();
  if (!reflectionText || reflectionText.length < 40) return;

  // 4. Embed and store the reflection
  const reflEmbResult = await env.AI.run(embModel.id as any, {
    text: [reflectionText],
  });
  const reflVector = (reflEmbResult as any).data?.[0];
  if (!reflVector) return;

  const reflectionId = `refl_\({newDocId}_\){Date.now()}`;

  await env.VECTORIZE.upsert([
    {
      id: reflectionId,
      values: reflVector,
      metadata: {
        content: reflectionText,
        doc_type: 'reflection',
        parent_id: newDocId,
        reflection_score: REFLECTION_BOOST,
        source_doc_ids: relatedDocs.map(m => m.id).join(','),
        date_created: new Date().toISOString(),
      },
    },
  ]);

  await env.DB.prepare(
    `INSERT INTO documents
     (id, content, doc_type, reflection_score, parent_id, date_created)
     VALUES (?, ?, 'reflection', ?, ?, ?)`
  )
    .bind(reflectionId, reflectionText, REFLECTION_BOOST, newDocId, new Date().toISOString())
    .run();

  // 5. Check if consolidation is due
  const recentCount = await env.DB
    .prepare(`SELECT COUNT(*) as cnt FROM documents WHERE doc_type = 'reflection' AND date_created > datetime('now', '-1 hour')`)
    .first<{ cnt: number }>();

  if ((recentCount?.cnt ?? 0) >= CONSOLIDATION_THRESHOLD) {
    await consolidate(env);
  }
}

Two things worth noting here.

First, the semantic threshold (score > 0.65) matters. Too low and you're synthesising unrelated documents. Too high and you're rarely finding connections. 0.65 works well with bge-small. You can bump it to 0.72 with qwen3-0.6b (1024d) where scores cluster higher.

The prompt structure is deliberate. Three sentences, each doing a specific job: what's new, how it connects, what remains. This keeps reflections useful for retrieval. A freeform synthesis prompt produces beautiful prose that doesn't retrieve well. This structure produces retrievable artifacts.

Step 3: Consolidation

As reflections accumulate, they need their own synthesis layer — otherwise you're adding noise at a higher abstraction level.

Add this to src/engines/reflection.ts:

export async function consolidate(env: Env): Promise<void> {
  // Fetch recent reflections not yet consolidated
  const recent = await env.DB
    .prepare(
      `SELECT id, content FROM documents
       WHERE doc_type = 'reflection'
       AND id NOT IN (
         SELECT DISTINCT parent_id FROM documents
         WHERE doc_type = 'summary' AND parent_id IS NOT NULL
       )
       ORDER BY date_created DESC
       LIMIT 6`
    )
    .all<{ id: string; content: string }>();

  if (!recent.results || recent.results.length < CONSOLIDATION_THRESHOLD) return;

  const reflectionTexts = recent.results.map((r, i) => `Reflection \({i + 1}: \){r.content}`).join('\n\n');

  const prompt = `You are consolidating multiple knowledge reflections into a single compressed insight.

${reflectionTexts}

Write two to three sentences that capture the most important cross-cutting pattern or tension across these reflections. What does the knowledge base now understand that it didn't before these documents were added? What's the most important open question?

Be precise. No preamble.`;

  const reflModel = resolveReflectionModel(env.REFLECTION_MODEL);
  const llmResp = await env.AI.run(reflModel.id as any, {
    messages: [{ role: 'user', content: prompt }],
    max_tokens: 320,
  });

  const summaryText = (llmResp as any)?.response?.trim();
  if (!summaryText || summaryText.length < 40) return;

  const embModel = resolveEmbeddingModel(env.EMBEDDING_MODEL);
  const embResult = await env.AI.run(embModel.id as any, { text: [summaryText] });
  const summaryVector = (embResult as any).data?.[0];
  if (!summaryVector) return;

  const summaryId = `summary_${Date.now()}`;

  await env.VECTORIZE.upsert([
    {
      id: summaryId,
      values: summaryVector,
      metadata: {
        content: summaryText,
        doc_type: 'summary',
        reflection_score: REFLECTION_BOOST * 1.2,
        source_reflection_ids: recent.results.map(r => r.id).join(','),
        date_created: new Date().toISOString(),
      },
    },
  ]);

  await env.DB.prepare(
    `INSERT INTO documents (id, content, doc_type, reflection_score, date_created)
     VALUES (?, ?, 'summary', ?, ?)`
  )
    .bind(summaryId, summaryText, REFLECTION_BOOST * 1.2, new Date().toISOString())
    .run();
}

Summaries get a 1.2× multiplier on top of the base reflection boost. In search results, a summary synthesising twelve related documents should rank above any single document chunk on broad conceptual queries. On specific factual queries, the raw chunks will score higher. The ranking sorts itself.

Step 4: Wire It Into Your Ingest Handler

The reflection runs as a background job. It doesn't block the ingest response — that would add 2–3 seconds to every ingest call.

In your src/handlers/ingest.ts, after you've stored the document:

import { reflect } from '../engines/reflection';

// ... existing ingest logic ...

// After VECTORIZE.upsert() and DB insert succeed:
ctx.waitUntil(
  reflect(documentId, content, env).catch(err => {
    console.warn('[reflection] failed for', documentId, err.message);
  })
);

return new Response(JSON.stringify({
  success: true,
  documentId,
  chunks: chunkCount,
  // ... rest of response
}), { headers: { 'Content-Type': 'application/json' } });

ctx.waitUntil() is the Cloudflare Workers primitive for background work. The response returns immediately. The reflection runs after. The ingest API stays fast.

The .catch() is important. A failed reflection should never fail an ingest. Raw documents are the source of truth. Reflections are derived value — useful, but not critical path.

Step 5: Boost Reflections in Search

Add the reflection boost to your ranking logic in src/engines/hybrid.ts. After RRF fusion and before returning results:

// Apply reflection boost
const boosted = results.map(r => ({
  ...r,
  score: r.doc_type === 'reflection' || r.doc_type === 'summary'
    ? r.score * (r.reflection_score ?? 1.5)
    : r.score,
}));

return boosted.sort((a, b) => b.score - a.score);

This is a post-fusion boost, not a pre-fusion rerank. The reasoning: apply RRF across all results first, so reflections earn their place on raw relevance before getting boosted. A reflection that would not rank in the top 20 on raw similarity shouldn't appear just because it has a boost multiplier.

Step 6: Filtering by doc_type

Your search endpoint should accept a doc_type filter so callers can control what they see:

// In your search request handler:
const docTypeFilter = body.filters?.doc_type;

// Pass to Vectorize query:
const vectorFilter: Record<string, unknown> = {};
if (docTypeFilter) {
  vectorFilter.doc_type = docTypeFilter;
}

This gives callers three modes:

# Only reflections and summaries
POST /search
{ "query": "pricing decisions", "filters": { "doc_type": { "$in": ["reflection", "summary"] } } }

# Only source documents
POST /search
{ "query": "pricing decisions", "filters": { "doc_type": { "$eq": "raw" } } }

# Default: all types, reflections boosted
POST /search
{ "query": "pricing decisions" }

The default (no filter) is the most useful. Let the boost do its job. Restrict to raw when you need citations. Restrict to reflections when you want the synthesised view.

What Changes After You Build This

At 200 documents, the difference becomes noticeable. Queries that previously returned five fragmented chunks now surface a reflection that already synthesised those chunks. Broad conceptual queries — "what do we know about X?" — start returning genuinely useful summaries instead of just the most-similar individual paragraph.

At 2,000 documents, the reflection layer is the most valuable part of the system. The raw chunks answer specific factual questions. The reflections and summaries answer conceptual questions that could not be answered from any single document. The system has learned something no individual document contains.

One failure mode worth knowing: if your embedding model has poor semantic clustering — old bge-small at 384d with mixed-domain documents — the related-documents retrieval step will surface weak connections and produce shallow reflections. The 0.65 threshold filters most of this out, but if you're seeing reflections that seem off-topic, your embeddings are the first thing to check.

Deploying

wrangler d1 execute mcp-knowledge-db --remote --file=./migrations/003_add_reflection_fields.sql
wrangler deploy

Then ingest a few documents and watch what happens:

# Ingest document 1
curl -X POST https://your-worker.workers.dev/ingest \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "doc-001", "content": "Your document text here..."}'

# After a few seconds, check if a reflection was created
curl "https://your-worker.workers.dev/search" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "your topic", "filters": {"doc_type": {"$eq": "reflection"}}}'

Reflections won't appear until there are related documents to synthesise. Ingest at least three documents on similar topics before expecting to see them.

What to Build Next

The reflection layer as described here fires after every ingest. That's expensive at high ingest volume: if you're batch-importing 10,000 documents, you don't want 10,000 individual reflection calls.

For bulk ingestion, gate it: call reflect() only when a document's similarity search returns a match above 0.8, or batch-run reflection after the bulk import completes. The POST /ingest/batch endpoint in the full repo does this.

The second thing worth building: surfacing reflections in your UI with a visual distinction. A search result that's a reflection should look different from a raw chunk. In the dashboard included in the repo, reflections render with a 💡 badge and a "synthesised from N documents" note.

Full source at github.com/dannwaneri/vectorize-mcp-worker — reflection engine, consolidation, batch ingest, dashboard, OpenAPI spec.

The codebase is TypeScript, deploys with a single wrangler deploy, runs for roughly $1–5/month at 10,000 queries/day.

Standard RAG retrieves. This learns.

Sometimes you need to combine reports or invoices, or simply merge multiple documents into a single clean file.

Most tools that handle this either require installing software or uploading files to a server, which can be slow and not always ideal – especially when dealing with private documents.

But what if you could merge PDFs directly in the browser, without any backend?

That’s exactly what we’ll build in this tutorial.

By the end, you’ll have a fully working browser-based PDF merger. It will allow users to upload files, preview them, reorder documents using drag-and-drop, select specific pages, and download the final merged PDF instantly.

Table of Contents

1. How PDF Merging Works in the Browser

2. Project Setup

3. What Library Are We Using?

4. Creating the Upload Interface

5. Rendering PDF Previews

6. Reordering Files Drag and Drop

7. Sorting and Reordering PDFs (Important)

8. Merging PDFs Using JavaScript

9. Improving User Experience

10. Demo: How the PDF Merger Works

11. Important Notes from Real-World Use

12. Common Mistakes to Avoid

13. Conclusion

How PDF Merging Works in the Browser

At a high level, merging PDFs means loading multiple PDF files, extracting pages from each, and combining them into a single document.

Traditionally, this process happens on a server. Files are uploaded, processed, and then returned to the user.

But modern JavaScript libraries make it possible to do all of this directly in the browser. Instead of sending files anywhere, the entire process runs locally on the user’s device.

This approach has a few practical advantages. It makes the process faster because there’s no upload time involved. It also improves privacy, since files never leave the user’s system. And from a development perspective, it removes the need for backend processing altogether.

Project Setup

We’ll keep this project simple.

You only need:

• an HTML file

• JavaScript

• a few libraries

No backend required.

What Library Are We Using?

We’ll use two important libraries:

<script src="https://unpkg.com/pdf-lib@1.17.1/dist/pdf-lib.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/pdf.js/2.16.105/pdf.min.js"></script>

• We'll use pdf-lib to merge and modify PDFs

• We'll use pdf.js to render previews in the browser

This combination is very powerful and commonly used in real projects.

Creating the Upload Interface

Start with a simple drag-and-drop area:

<div id="upload-area">
  <input type="file" id="file-input" multiple accept="application/pdf">
</div>

Users can either drag files or click to select.

Once files are selected, we read them using:

const arrayBuffer = await file.arrayBuffer();

This allows us to pass the file into our PDF libraries.

Rendering PDF Previews

To improve usability, we'll show a preview of each uploaded PDF.

Using pdf.js, we can render pages like this:

const pdf = await pdfjsLib.getDocument(arrayBuffer).promise;
const page = await pdf.getPage(1);

const viewport = page.getViewport({ scale: 1.5 });
canvas.height = viewport.height;
canvas.width = viewport.width;

page.render({
  canvasContext: context,
  viewport: viewport
});

This gives users visual feedback before merging.

Reordering Files (Drag and Drop)

Order matters when merging PDFs.

Instead of forcing users to upload in sequence, we'll allow reordering.

We can use a library like Sortable.js for this:

new Sortable(document.getElementById('pdf-grid'), {
  animation: 150
});

This enables drag-and-drop sorting and instant visual updates.

Sorting and Reordering PDFs (Important)

This is where the tool becomes more practical in real-world use.

Instead of forcing users to upload files in a specific order, the tool allows them to rearrange PDFs before merging.

Users can manually drag and drop files to adjust the sequence, or use built-in sorting options such as arranging files alphabetically or by file size. This makes it easy to quickly organize multiple documents without re-uploading them.

This flexibility ensures that the final merged document follows the exact order the user needs. In real-world scenarios, this is especially useful when combining reports, invoices, or other documents where sequence is important.

Here’s a simple example of how you might sort uploaded files:

function sortFiles(files, type) {
  return files.sort((a, b) => {
    if (type === "name-asc") {
      return a.name.localeCompare(b.name);
    }

    if (type === "name-desc") {
      return b.name.localeCompare(a.name);
    }

    if (type === "size-asc") {
      return a.size - b.size;
    }

    if (type === "size-desc") {
      return b.size - a.size;
    }

    return 0;
  });
}

This allows precise control over what gets merged.

Merging PDFs Using JavaScript

Now comes the core logic. We'll use pdf-lib to combine pages:

const { PDFDocument } = PDFLib;

const mergedPdf = await PDFDocument.create();

for (const file of files) {
  const pdf = await PDFDocument.load(file.arrayBuffer);
  const pages = await mergedPdf.copyPages(pdf, selectedPages);

  pages.forEach(page => mergedPdf.addPage(page));
}

const pdfBytes = await mergedPdf.save();

Finally, we'll create a downloadable file:

const blob = new Blob([pdfBytes], { type: 'application/pdf' });

Improving User Experience

A simple merge tool works, but a good tool feels smooth.

Small improvements make a big difference.

For example:

• showing previews before merging

• allowing users to remove files

• enabling page navigation

• providing instant feedback

These details turn a basic feature into a real product.

Demo: How the PDF Merger Works

Here’s how the full flow looks in practice:

Step 1: Upload PDFs

Users can drag and drop PDF files into the upload area or select them manually.

Step 2: Preview Files

Each uploaded file is displayed with a preview as well as pdf files details (name, size, nos of page, and so on), so users can verify the content before merging.

Step 3: Reorder Files

Users can arrange the order of PDFs using drag-and-drop or sorting options as well as manual options. This ensures the final merged document follows the correct sequence.

Step 4: Merge PDFs

Once everything is arranged, users can click the merge button to combine all selected PDFs into a single file.

Step 5: Download the Final PDF

The merged PDF is generated instantly in the browser, and users can preview , rename, and download it without any server interaction.

Important Notes from Real-World Use

When building tools like a PDF merger, handling large files efficiently becomes important.

If multiple large PDFs are loaded at once, it can slow down the browser or consume too much memory. Instead of processing everything at once, it’s better to handle files step by step.

For example, instead of loading all PDFs together, you can process them one by one:

const { PDFDocument } = PDFLib;

const mergedPdf = await PDFDocument.create();

for (const file of files) {
  const arrayBuffer = await file.arrayBuffer();
  const pdf = await PDFDocument.load(arrayBuffer);

  const pages = await mergedPdf.copyPages(pdf, pdf.getPageIndices());

  pages.forEach(page => mergedPdf.addPage(page));
}

This approach keeps memory usage lower and avoids freezing the browser when working with larger files.

You can also improve performance by limiting file size or the number of files users can upload at once. This helps keep the tool responsive even on lower-powered devices.

Another important aspect is privacy. Since everything runs directly in the browser, files are never uploaded to a server. This means sensitive documents stay on the user’s device.

But it’s still important to be transparent about this. In real-world tools, you should clearly mention that all processing happens locally and no files are stored or transmitted.

This client-side approach improves both performance and user trust, especially when working with private or confidential documents.

Common Mistakes to Avoid

A common mistake is skipping validation. If users upload invalid files or empty inputs, the merge process can fail.

Another issue is ignoring page ranges. If parsing is incorrect, users may get unexpected results.

Also, relying on fixed layouts or assumptions can break the experience across different files. Testing with different PDF types is important.

Conclusion

In this tutorial, you built a browser-based PDF merger using JavaScript.

More importantly, you learned how to process files locally in the browser, render previews for better usability, handle user input safely, and manage dynamic document structures when working with PDFs.

This approach removes the need for a backend and keeps everything fast, private, and efficient.

Once you understand this pattern, you can extend it to build more advanced tools. For example, you could create features like PDF splitting, compression, editing, or other document-based utilities using the same core ideas.

And that’s where things start getting really interesting.

That frustration made the problem feel very clear to me: it was not about having fewer clothes. It was about having better organization, better visibility, and better guidance when making outfit decisions.

So I built a fashion web app that helps users organize their wardrobe, get outfit suggestions, evaluate shopping decisions, and improve recommendations over time using feedback.

In this article, I’ll walk through what the app does, how I built it, the decisions I made along the way, and the challenges that shaped the final result.

Table of Contents

• Table of Contents

• What the App Does

• Why I Built It

• Tech Stack

• Product Walkthrough (What Users See)

• How I Built It

• Challenges I Faced

• What I Learned

• What I Want to Improve Next

• Future Improvements

• Conclusion

What the App Does

At a high level, the app combines six core capabilities:

1. Wardrobe management

2. Outfit recommendations

3. Shopping suggestions

4. Discard recommendations

5. Feedback and usage tracking

6. Secure multi-user accounts

Users can upload clothing items, explore suggested outfits, and mark recommendations as helpful or not helpful. They can also rate outfits and track whether items are worn, kept, or discarded.

That feedback becomes structured data for improving future recommendation quality.

Why I Built It

I wanted to create something that felt personal and actually useful. A lot of fashion apps look polished, but they do not always help with everyday decisions. My goal was to build something that could make wardrobe management easier and outfit selection less overwhelming. The app needed to do three things well:

• store each user’s wardrobe data

• personalize recommendations

• learn from user feedback over time .

That feedback loop mattered to me because it makes the app feel more alive instead of static.

Tech Stack

Here are the tools I used to built the app:

• Frontend: React + Vite

• Backend: FastAPI

• Database: SQLite (local development)

• Background jobs: Celery + Redis

• Authentication: JWT (access + refresh token flow)

• Deployment support: Docker and GitHub Codespaces

This ended up giving me a pretty modular setup, which helped a lot as features started increasing: fast frontend iteration, clean API boundaries, and room to evolve recommendations separately from UI.

Product Walkthrough (What Users See)

1. Onboarding and Account Setup

To start using the app, a user needs to register, verify their email, and complete some profile basics.

Each account is isolated, so wardrobe history and recommendations stay user-specific.

In this onboarding screen above, you can see account creation, email verification, and profile fields for body shape, height, weight, and style preferences.

2. Wardrobe Upload

Users can upload clothing images .

Image analysis labels each item and makes it searchable for recommendations. The wardrobe upload form shows image analysis results with category, dominant color, secondary color, and pattern details listed.

3. Outfit Recommendations

Users can request recommendations, then rate outputs.

Above you can see the outfit recommendation dashboard that shows ranked outfit cards with feedback and rating actions. Recommendations are ranked by a weighted scoring model.

4. Shopping and Discard Assistants

The app evaluates new items against existing wardrobe data and flags low-value wardrobe items that may be worth removing.

You can see the recommendation scores, written reasons (not just a binary decision), and styling guidance for each item above. It also features a "how to style it" incase the user still wants to keep the item.

How I Built It

1. Frontend Setup (React + Vite)

I used React + Vite because I wanted fast iteration and a clean component structure.

The frontend is split into feature areas like onboarding, wardrobe management, outfits, shopping, and discarded-item suggestions. I also keep API calls in a service layer so the UI components stay focused on rendering and interaction.

The snippet below is a simplified example of the API service pattern used in the app. It is not meant to be copy-pasted as-is, but it shows the same structure the frontend uses when talking to the backend.

Example API client pattern:

export async function getOutfitRecommendations(userId, params = {}) {
  const query = new URLSearchParams(params).toString();
  const url = `/users/\({userId}/outfits/recommend\){query ? `?${query}` : ""}`;

  const response = await fetch(url, {
    headers: {
      Authorization: `Bearer ${localStorage.getItem("access_token")}`,
    },
  });

  if (!response.ok) {
    throw new Error("Failed to fetch outfit recommendations");
  }

  return response.json();
}

Here's what's happening in that snippet:

• URLSearchParams builds optional query strings like occasion, season, or limit.

• The request path is user-scoped, which keeps each user’s recommendations isolated.

• The Authorization header sends the access token so the backend can verify the session.

• The response is checked before parsing so the UI can surface a useful error if the request fails.

This pattern kept the frontend simple and reusable as the number of API calls grew.

2. Backend Architecture with FastAPI

The backend is organized around clear route groups:

• auth routes for register, login, refresh, logout, and sessions

• user analysis routes

• wardrobe CRUD routes

• recommendation routes for outfits, shopping, and discard analysis

• feedback routes for ratings and helpfulness signals

One of the most important design choices was enforcing ownership checks on user-scoped resources. That prevented one user from accessing another user’s wardrobe or feedback data.

The backend snippet below is another simplified example from the app’s route layer. It shows the request validation and orchestration logic, while the actual scoring work stays in the recommendation service.

@app.get("/users/{user_id}/outfits/recommend")
def recommend_outfits(user_id: int, occasion: str | None = None, season: str | None = None, limit: int = 10):
    user = get_user_or_404(user_id)
    wardrobe_items = get_user_wardrobe(user_id)

    if len(wardrobe_items) < 2:
        raise HTTPException(status_code=400, detail="Not enough wardrobe items")

    recommendations = outfit_generator.generate_outfit_recommendations(
        wardrobe_items=wardrobe_items,
        body_shape=user.body_shape,
        undertone=user.undertone,
        occasion=occasion,
        season=season,
        top_k=limit,
    )

    return {"user_id": user_id, "recommendations": recommendations}

Here's how to read that code:

• get_user_or_404 loads the profile data needed for personalization.

• get_user_wardrobe fetches only the current user’s items.

• The minimum wardrobe check prevents the recommendation logic from running on incomplete data.

• generate_outfit_recommendations handles the scoring logic separately, which keeps the route handler small and easier to test.

• The response returns the results in a shape the frontend can consume directly.

That separation helped keep the API layer readable while the recommendation logic stayed isolated in its own service.

3. Recommendation Logic

I intentionally started with deterministic rules before introducing heavy ML. That made behavior easier to debug and explain.

The outfit recommender scores combinations using weighted signals:

$$\text{outfit score} = 0.4 \cdot \text{color harmony} + 0.4 \cdot \text{body-shape fit} + 0.2 \cdot \text{undertone fit}$$

The snippet below is a simplified example from the recommendation engine. It shows how the app combines multiple signals into a single score:

def score_outfit(combo, user_context):
    color_score = color_harmony.score(combo)
    shape_score = body_shape_rules.score(combo, user_context.body_shape)
    undertone_score = undertone_rules.score(combo, user_context.undertone)

    total = 0.4 * color_score + 0.4 * shape_score + 0.2 * undertone_score
    return round(total, 3)

The logic behind this approach is straightforward:

• color harmony helps the outfit feel visually coherent

• body-shape scoring helps the outfit feel flattering

• undertone scoring helps the colors work better with the user’s profile

I used a similar structure for discard recommendations and shopping suggestions, but with different factors and thresholds.

4. Authentication and Secure Multi-user Design

Security was one of the most important parts of this build.

I implemented:

• short-lived access tokens

• refresh tokens with JTI tracking

• token rotation on refresh

• session revocation (single session and all sessions)

• email verification and password reset flows

The snippet below is a simplified example of the refresh-token lifecycle used in the app. It shows the important control points rather than every helper function:

def refresh_access_token(refresh_token: str):
    payload = decode_jwt(refresh_token)
    jti = payload["jti"]

    token_record = db.get_refresh_token(jti)
    if not token_record or token_record.revoked:
        raise AuthError("Invalid refresh token")

    new_refresh, new_jti = issue_refresh_token(payload["sub"])
    token_record.revoked = True
    token_record.replaced_by_jti = new_jti

    new_access = issue_access_token(payload["sub"])
    return {"access_token": new_access, "refresh_token": new_refresh}

What this code is doing:

• It decodes the refresh token and looks up its JTI in the database.

• It rejects reused or revoked sessions, which helps prevent replay attacks.

• It rotates the refresh token instead of reusing it.

• It issues a fresh access token so the session stays valid without forcing the user to log in again.

This design made multi-device sessions safer and gave me server-side control over logout behavior.

5. Background Jobs for Long-running Operations

Image analysis can be expensive, especially when the app needs to classify clothing, analyze colors, and estimate body-shape-related signals. To keep the request path responsive, I added Celery + Redis support for background tasks.

That gave the app two modes:

• synchronous processing for simpler local development

• queued processing for heavier or slower jobs

That tradeoff mattered because it let me keep the developer experience simple without blocking the app during more expensive work.

6. Data Model and Feedback Capture

A recommendation system only improves if it captures the right signals.

So I added dedicated feedback tables for:

• outfit ratings (1-5 + optional comments)

• recommendation helpful/unhelpful feedback

• item usage actions (worn/kept/discarded)

Here is the shape of one of those models:

class RecommendationFeedback(Base):
    __tablename__ = "recommendation_feedback"

    id = Column(Integer, primary_key=True)
    user_id = Column(Integer, ForeignKey("users.id"), nullable=False)
    recommendation_type = Column(String(50), nullable=False)
    recommendation_id = Column(Integer, nullable=False)
    helpful = Column(Boolean, nullable=False)
    created_at = Column(DateTime, default=datetime.utcnow)

How to read this model:

• user_id ties feedback to the person who gave it.

• recommendation_type tells me whether the feedback belongs to outfits, shopping, or discard suggestions.

• recommendation_id identifies the exact recommendation.

• helpful stores the user’s direct response.

• created_at makes it possible to analyze feedback trends over time.

This part of the system gives the app a real learning foundation, even though the feedback-to-model-update loop is still a future improvement.

Challenges I Faced

This was the section that taught me the most.

1. Image-heavy endpoints were slower than I wanted

The analyze and wardrobe upload flows were doing a lot of work at once: image validation, classification, color extraction, storage, and database writes.

At first, that made the request flow feel heavier than it should have.

What I changed:

• I bounded concurrent image jobs so the app wouldn't try to do too much at once.

• I separated slower jobs into background processing where possible.

• I used load-test results to confirm which endpoints were actually expensive.

The practical effect was that heavy image requests stopped competing with each other so aggressively. Instead of letting many expensive tasks pile up inside the same request cycle, I limited the active work and pushed slower operations into the queue when needed.

Why this fixed it:

• Bounding concurrency prevented the system from overloading CPU-bound tasks.

• Moving expensive work into async jobs kept the main request/response cycle more responsive.

• Load testing gave me evidence instead of guesswork, so I could tune the system based on real performance behavior.

In other words, I didn't just “optimize” the endpoint in theory. I changed the execution model so expensive analysis could not block every other request behind it.

2. JWT sessions needed real server-side control

A basic JWT setup is easy to get working, but it becomes less useful if you cannot revoke sessions or manage multiple devices cleanly.

What I changed:

• I stored refresh tokens in the database.

• I tracked token JTI values.

• I rotated refresh tokens when users refreshed their session.

• I added endpoints for logging out a single session or all sessions.

The important shift here was moving from “token exists, therefore session is valid” to “token exists, matches the database record, and has not been revoked or replaced.” That gave the server the authority to invalidate old sessions immediately.

Why this fixed it:

• Server-side token tracking made revocation possible.

• Rotation reduced the chance of token reuse.

• Session management became visible to the user, which made the app feel more trustworthy.

This is what made logout-all and multi-device management work in a real way instead of just being cosmetic UI actions.

3. User data isolation had to be explicit

Because this is a multi-user app, I had to be careful that one account could never accidentally see another account’s wardrobe data.

What I changed:

• I added ownership checks to user-scoped routes.

• I kept all wardrobe and feedback queries filtered by user_id.

• I used encrypted image storage instead of exposing raw paths.

In practice, this meant every route had to ask the same question: “Does this user own the resource they are trying to access?” If the answer was no, the request stopped immediately.

Why this fixed it:

• Ownership checks made data access rules explicit.

• User-filtered queries prevented accidental cross-account reads.

• Encrypted storage improved privacy and reduced the risk of exposing image data directly.

That combination is what kept wardrobe data, feedback history, and images separated correctly across accounts.

4. Docker made the project easier to share, but only after the stack was organized

The app includes the frontend, backend, Redis, Celery worker, and Celery Beat, so the first challenge was making the setup feel reproducible instead of fragile.

What I changed:

• I defined the stack in Docker Compose.

• I documented the required environment variables.

• I kept the dev stack aligned with how the app runs in practice.

This removed a lot of setup ambiguity. Instead of asking someone to manually figure out how the frontend, backend, Redis, and workers fit together, I made the stack describe itself.

Why this fixed it:

• Docker let contributors start the project with fewer manual steps.

• Clear environment configuration reduced setup mistakes.

• Matching the stack to the architecture made the app easier to understand and test.

That was important because the app depends on several moving parts, and the simplest way to make the project approachable was to make startup behavior predictable.

What I Learned

This project taught me a few important lessons:

• Small features become much more valuable when they work together.

• Feedback data is one of the strongest signals for improving recommendations.

• Clean data modeling matters a lot when multiple users are involved.

• Docker and clear setup instructions make a project much easier for other people to try.

I also learned that a project does not need to be huge to be useful. A focused app that solves one problem well can still feel meaningful.

What I Want to Improve Next

My roadmap from here:

1. Integrate feedback directly into ranking updates

2. Add visual analytics for recommendation quality trends

3. Improve mobile UX parity

4. Deploy with persistent cloud storage and production database defaults

5. Provide a public demo mode for easier evaluation

Future Improvements

There are still a few things I would like to add later:

• a more advanced recommendation engine

• visual analytics for user feedback

• better mobile support

• live deployment with persistent cloud storage

• a public demo mode for easier testing

Conclusion

This project began as a personal frustration and turned into a full web application with authentication, wardrobe storage, recommendation logic, and feedback infrastructure.

The most rewarding part was seeing how practical software decisions, not just flashy UI, can help people make everyday choices faster.

If you want to explore or run the project, check out the repo. You can try the flows and share feedback. I would especially love input on recommendation quality, UX clarity, and what features would make this genuinely useful in daily life.

A character count doesn't need GPT-4. A presence check doesn't need Sonnet. A regex doesn't need anything except Python.

The mistake isn't using AI — it's not knowing when to stop using it.

This tutorial shows you how to build a tiered routing system that sends tasks to the cheapest model that can solve them. The pattern is called the cost curve. It comes from a comment thread on a DEV.to article, implemented by three developers over a weekend, and it cut the per-URL cost of a real SEO audit agent from \(0.006 to effectively \)0 for most pages.

By the end, you'll have a working cost_curve.py module you can drop into any agent project.

What You'll Build

A three-tier routing function that:

• Runs deterministic Python checks first — zero API cost

• Escalates to Claude Haiku only for genuinely ambiguous cases — ~$0.0001 per call

• Escalates to Claude Sonnet only when semantic judgment is required — ~$0.006 per call

• Falls back gracefully when any tier fails

• Returns a consistent result schema regardless of which tier handled the request

The full implementation is part of dannwaneri/seo-agent, an open-core SEO audit agent. The cost curve module is the premium routing layer, and the principle applies to any agent with mixed-complexity tasks.

Prerequisites

• Python 3.11 or higher

• An Anthropic API key

• Basic familiarity with Python and the Claude API

Table of Contents

1. The Problem with Calling Claude on Everything

2. The Cost Curve Explained

3. Project Setup

4. Tier 1: Deterministic Python

5. Tier 2: Claude Haiku for Ambiguous Cases

6. Tier 3: Claude Sonnet for Semantic Judgment

7. The Router: audit_url()

8. Graceful Fallback

9. Testing the Cost Curve

10. Applying This Pattern to Your Agent

The Problem with Calling Claude on Everything

Here's what most agent code looks like:

def audit_url(snapshot: dict) -> dict:
    response = client.messages.create(
        model="claude-sonnet-4-20250514",
        messages=[{"role": "user", "content": build_prompt(snapshot)}]
    )
    return parse_response(response)

This works. It also calls Sonnet for every URL in the list — including the ones where the title is 142 characters long and the answer is obviously FAIL without any model involvement.

Claude Sonnet 4 is priced at \(3 per million input tokens and \)15 per million output tokens. A typical page snapshot is around 500 input tokens. That's \(0.0015 per URL just for input — before output tokens. Across a 20-URL weekly audit, the total is around \)0.12. Not expensive. But most of those pages have mechanical SEO issues: missing descriptions, titles over 60 characters, no canonical tag. A character count catches all of that. You don't need a model.

The cost curve fixes this by routing based on what the task actually requires, not on what the model is capable of.

The Cost Curve Explained

In the cost curve, we have three tiers, three tools, and three price points:

Tier 1 — Deterministic Python. Cost: $0. Check title length, description length, H1 count, canonical presence. These are not judgment calls. They're string operations. If title length > 60, FAIL. No model needed.

Tier 2 — Claude Haiku. Cost: ~$0.0001 per call. Title present but only 4 characters long. Description present but only 30 characters. Status code is a redirect. These pass the mechanical audit but something is off. Haiku is fast and cheap enough that escalating ambiguous cases costs less than the debugging time you'd spend on false positives.

Tier 3 — Claude Sonnet. Cost: ~$0.006 per call. Pages Haiku flags as needing semantic judgment. "This title passes length but reads like a navigation label." "This description duplicates the title verbatim." Sonnet earns its cost on genuinely hard cases — not on every URL in the list.

The routing decision happens before any API call. The result schema is identical regardless of which tier handled the request.

Project Setup

mkdir cost-curve-demo && cd cost-curve-demo
pip install anthropic

Set your API key:

# macOS/Linux
export ANTHROPIC_API_KEY="sk-ant-..."

# Windows PowerShell
$env:ANTHROPIC_API_KEY = "sk-ant-..."

Create cost_curve.py — you'll build this module step by step.

Tier 1: Deterministic Python

Tier 1 runs first on every URL. It checks four fields using only Python string operations. There's no API call, no latency, and no cost.

import json
import logging
import os
import re
from datetime import datetime, timezone

import anthropic

logger = logging.getLogger(__name__)

REDIRECT_CODES = {301, 302, 307, 308}

# Fields that trigger Tier 2 escalation
# Title or description present but suspiciously short
AMBIGUOUS_TITLE_MAX = 10   # chars — present but too short to be real
AMBIGUOUS_DESC_MAX = 50    # chars — present but too short to be useful


def _now_iso() -> str:
    return datetime.now(timezone.utc).isoformat()


def _build_result(snapshot: dict, method: str) -> dict:
    """Base result skeleton — same schema regardless of tier."""
    return {
        "url": snapshot.get("final_url", ""),
        "final_url": snapshot.get("final_url", ""),
        "status_code": snapshot.get("status_code"),
        "title": {"value": None, "length": 0, "status": "PASS"},
        "description": {"value": None, "length": 0, "status": "PASS"},
        "h1": {"count": 0, "value": None, "status": "PASS"},
        "canonical": {"value": None, "status": "PASS"},
        "flags": [],
        "human_review": False,
        "audited_at": _now_iso(),
        "method": method,
        "needs_tier3": False,
    }


def tier1_check(snapshot: dict) -> dict:
    """
    Pure Python SEO checks. Zero API calls.

    Returns a result dict with method="deterministic".
    Sets needs_tier3=False always — Tier 1 never escalates to Tier 3 directly.
    Escalation to Tier 2 is decided by the router, not here.
    """
    result = _build_result(snapshot, "deterministic")

    title = snapshot.get("title") or ""
    description = snapshot.get("meta_description") or ""
    h1s = snapshot.get("h1s") or []
    canonical = snapshot.get("canonical") or ""

    # Title check
    result["title"]["value"] = title or None
    result["title"]["length"] = len(title)
    if not title or len(title) > 60:
        result["title"]["status"] = "FAIL"
        msg = "Title is missing" if not title else f"Title is {len(title)} characters (max 60)"
        result["flags"].append(msg)

    # Description check
    result["description"]["value"] = description or None
    result["description"]["length"] = len(description)
    if not description or len(description) > 160:
        result["description"]["status"] = "FAIL"
        msg = "Meta description is missing" if not description else f"Meta description is {len(description)} characters (max 160)"
        result["flags"].append(msg)

    # H1 check
    result["h1"]["count"] = len(h1s)
    result["h1"]["value"] = h1s[0] if h1s else None
    if len(h1s) == 0:
        result["h1"]["status"] = "FAIL"
        result["flags"].append("H1 tag is missing")
    elif len(h1s) > 1:
        result["h1"]["status"] = "FAIL"
        result["flags"].append(f"Multiple H1 tags found ({len(h1s)})")

    # Canonical check
    result["canonical"]["value"] = canonical or None
    if not canonical:
        result["canonical"]["status"] = "FAIL"
        result["flags"].append("Canonical tag is missing")

    return result

The key design decision: tier1_check() never decides whether to escalate. It just runs the checks and returns. The router decides escalation based on the result.

Tier 2: Claude Haiku for Ambiguous Cases

Tier 2 runs when Tier 1 detects something mechanical but the result might need a second look. A 4-character title present but clearly wrong. A 30-character description that's technically there but useless. A redirect status that needs a human-readable explanation.

Haiku is the right model here. It's fast, cheap (\(1 input / \)5 output per million tokens), and sufficient for triage-level judgment. The prompt asks a narrow question: is this ambiguous enough to need Sonnet?

def tier2_check(snapshot: dict) -> dict:
    """
    Claude Haiku call for ambiguous cases.

    Returns result with method="haiku".
    Sets needs_tier3=True if Haiku determines the case needs semantic judgment.
    Falls back to Tier 1 result on API error.
    """
    api_key = os.environ.get("ANTHROPIC_API_KEY")
    if not api_key:
        raise OSError("ANTHROPIC_API_KEY is not set.")

    client = anthropic.Anthropic(api_key=api_key)

    title = snapshot.get("title") or ""
    description = snapshot.get("meta_description") or ""
    status_code = snapshot.get("status_code")

    prompt = f"""You are an SEO auditor doing a quick triage check.

Page data:
- Title: {repr(title)} ({len(title)} chars)
- Meta description: {repr(description)} ({len(description)} chars)
- Status code: {status_code}

Answer these two questions with only "yes" or "no":
1. Does this page need semantic judgment beyond simple length/presence checks? 
   (e.g. title is present but clearly wrong, description is present but meaningless)
2. Is the status code a redirect that needs investigation?

Respond in this exact JSON format and nothing else:
{{"needs_tier3": true_or_false, "reason": "one sentence explanation"}}"""

    try:
        response = client.messages.create(
            model="claude-haiku-4-5-20251001",
            max_tokens=150,
            messages=[{"role": "user", "content": prompt}],
        )
        raw = response.content[0].text.strip()
        # Strip markdown fences if present
        if raw.startswith("```"):
            lines = raw.splitlines()
            raw = "\n".join(lines[1:-1] if lines[-1].strip() == "```" else lines[1:])
        parsed = json.loads(raw)

        result = _build_result(snapshot, "haiku")
        # Copy Tier 1 field checks — Haiku doesn't redo those
        t1 = tier1_check(snapshot)
        result["title"] = t1["title"]
        result["description"] = t1["description"]
        result["h1"] = t1["h1"]
        result["canonical"] = t1["canonical"]
        result["flags"] = t1["flags"]
        result["needs_tier3"] = parsed.get("needs_tier3", False)
        if result["needs_tier3"]:
            result["flags"].append(f"Escalated to Tier 3: {parsed.get('reason', '')}")

        return result

    except Exception as exc:
        logger.warning("[tier2] Haiku API error: %s — falling back to Tier 1 result", exc)
        fallback = tier1_check(snapshot)
        fallback["method"] = "haiku-fallback"
        return fallback

The fallback is the critical piece. If Haiku fails — rate limit, network error, malformed response — the function returns the Tier 1 result rather than crashing. The audit continues. The URL gets flagged with method="haiku-fallback" so you can identify it later.

Tier 3: Claude Sonnet for Semantic Judgment

Tier 3 is where the full extraction prompt runs. This is the same call you'd make in a naïve implementation — the difference is that only a small fraction of URLs reach this tier.

def tier3_check(snapshot: dict) -> dict:
    """
    Claude Sonnet call for semantic judgment.

    Returns result with method="sonnet".
    This is the full extraction prompt — same as calling the model directly.
    """
    api_key = os.environ.get("ANTHROPIC_API_KEY")
    if not api_key:
        raise OSError("ANTHROPIC_API_KEY is not set.")

    client = anthropic.Anthropic(api_key=api_key)

    prompt = f"""You are an SEO auditor. Analyze this page snapshot and return ONLY a JSON object.
No prose. No explanation. No markdown fences. Raw JSON only.

Page data:
- URL: {snapshot.get('final_url')}
- Status code: {snapshot.get('status_code')}
- Title: {snapshot.get('title')}
- Meta description: {snapshot.get('meta_description')}
- H1 tags: {snapshot.get('h1s')}
- Canonical: {snapshot.get('canonical')}

Return this exact schema:
{{
  "url": "string",
  "final_url": "string",
  "status_code": number,
  "title": {{"value": "string or null", "length": number, "status": "PASS or FAIL"}},
  "description": {{"value": "string or null", "length": number, "status": "PASS or FAIL"}},
  "h1": {{"count": number, "value": "string or null", "status": "PASS or FAIL"}},
  "canonical": {{"value": "string or null", "status": "PASS or FAIL"}},
  "flags": ["array of strings describing specific issues"],
  "human_review": false,
  "audited_at": "ISO timestamp"
}}

PASS/FAIL rules:
- title: FAIL if null or length > 60 characters, or if present but clearly not a real title
- description: FAIL if null or length > 160 characters, or if present but meaningless
- h1: FAIL if count is 0 or count > 1
- canonical: FAIL if null
- audited_at: use current UTC time"""

    try:
        response = client.messages.create(
            model="claude-sonnet-4-20250514",
            max_tokens=1000,
            messages=[{"role": "user", "content": prompt}],
        )
        raw = response.content[0].text.strip()
        if raw.startswith("```"):
            lines = raw.splitlines()
            raw = "\n".join(lines[1:-1] if lines[-1].strip() == "```" else lines[1:])

        result = json.loads(raw)
        result["method"] = "sonnet"
        result["needs_tier3"] = False
        return result

    except Exception as exc:
        logger.warning("[tier3] Sonnet API error: %s — falling back to Tier 1 result", exc)
        fallback = tier1_check(snapshot)
        fallback["method"] = "sonnet-fallback"
        return fallback

Note the prompt addition in Tier 3 that isn't in Tier 1: "or if present but clearly not a real title" and "or if present but meaningless". That's the semantic judgment Haiku identified as needed. Tier 3 acts on it.

The Router: audit_url()

The router is the public interface. Everything else is an implementation detail.

def audit_url(snapshot: dict, tiered: bool = False) -> dict:
    """
    Route a page snapshot through the appropriate audit tier.

    Args:
        snapshot: Page data from browser.py — must contain final_url,
                  status_code, title, meta_description, h1s, canonical.
        tiered: If False, delegates directly to Tier 3 (Sonnet).
                If True, routes through the cost curve.

    Returns:
        Audit result dict with method field indicating which tier ran.
    """
    if not tiered:
        # Non-tiered mode: call Sonnet directly, same as v1 behavior
        return tier3_check(snapshot)

    # Tier 1: always runs first
    t1_result = tier1_check(snapshot)

    # Check if escalation to Tier 2 is warranted
    title = snapshot.get("title") or ""
    description = snapshot.get("meta_description") or ""
    status_code = snapshot.get("status_code")

    needs_tier2 = (
        # Title present but suspiciously short
        (title and len(title) < AMBIGUOUS_TITLE_MAX) or
        # Description present but suspiciously short
        (description and len(description) < AMBIGUOUS_DESC_MAX) or
        # Redirect status — may need explanation
        (status_code in REDIRECT_CODES)
    )

    if not needs_tier2:
        # Tier 1 result is definitive — return without any API call
        return t1_result

    # Tier 2: Haiku triage
    t2_result = tier2_check(snapshot)

    if not t2_result.get("needs_tier3", False):
        # Haiku determined no semantic judgment needed
        return t2_result

    # Tier 3: Sonnet for semantic judgment
    return tier3_check(snapshot)

The router logic is explicit and readable. Each decision point is a named condition. When tiered=False, behavior is identical to the v1 naive implementation — this is the backward compatibility guarantee that lets you add the cost curve incrementally without breaking existing audits.

Graceful Fallback

The fallback pattern appears in both Tier 2 and Tier 3. It's worth making explicit:

# Pattern used in both tier2_check() and tier3_check()
except Exception as exc:
    logger.warning("[tierN] API error: %s — falling back to Tier 1 result", exc)
    fallback = tier1_check(snapshot)
    fallback["method"] = "tierN-fallback"
    return fallback

Three things this does:

1. Logs the error with enough context to debug later

2. Returns a valid result — the Tier 1 deterministic check always runs regardless

3. Tags the result with the fallback method so you can filter these in your report

An agent that crashes on API errors is not production-ready. An agent that degrades gracefully and continues is.

Testing the Cost Curve

Create test_cost_curve.py to verify routing behavior without live API calls:

import json
from unittest import mock

from cost_curve import audit_url, tier1_check


def make_snapshot(title="Normal Title Under 60 Chars",
                  description="A normal meta description that is under 160 characters and describes the page content well.",
                  h1s=["Single H1"],
                  canonical="https://example.com/page",
                  status_code=200,
                  final_url="https://example.com/page"):
    return {
        "title": title,
        "meta_description": description,
        "h1s": h1s,
        "canonical": canonical,
        "status_code": status_code,
        "final_url": final_url,
    }


def test_clean_page_returns_tier1_no_api_calls():
    """Clean page: all checks pass deterministically — no API call."""
    snapshot = make_snapshot()
    with mock.patch("anthropic.Anthropic") as mock_client:
        result = audit_url(snapshot, tiered=True)
        assert result["method"] == "deterministic"
        mock_client.assert_not_called()
    print("PASS: clean page → Tier 1, zero API calls")


def test_long_title_returns_tier1_fail_no_api_call():
    """Title >60 chars: FAIL from Tier 1, no API call."""
    snapshot = make_snapshot(title="A" * 70)
    with mock.patch("anthropic.Anthropic") as mock_client:
        result = audit_url(snapshot, tiered=True)
        assert result["method"] == "deterministic"
        assert result["title"]["status"] == "FAIL"
        mock_client.assert_not_called()
    print("PASS: title >60 → Tier 1 FAIL, zero API calls")


def test_suspiciously_short_title_escalates_to_tier2():
    """Title present but 4 chars: escalates to Tier 2."""
    snapshot = make_snapshot(title="SEO")  # 3 chars — under AMBIGUOUS_TITLE_MAX
    mock_response = mock.MagicMock()
    mock_response.content = [mock.MagicMock(
        text='{"needs_tier3": false, "reason": "title is short but not ambiguous"}'
    )]
    with mock.patch("anthropic.Anthropic") as mock_client:
        mock_client.return_value.messages.create.return_value = mock_response
        result = audit_url(snapshot, tiered=True)
        assert result["method"] == "haiku"
        assert mock_client.return_value.messages.create.call_count == 1
    print("PASS: short title → Tier 2 (Haiku called once)")


def test_tiered_false_calls_sonnet_directly():
    """tiered=False: Sonnet called regardless of snapshot content."""
    snapshot = make_snapshot()  # clean page, would be Tier 1 in tiered mode
    mock_response = mock.MagicMock()
    mock_response.content = [mock.MagicMock(text=json.dumps({
        "url": "https://example.com/page",
        "final_url": "https://example.com/page",
        "status_code": 200,
        "title": {"value": "Normal Title Under 60 Chars", "length": 27, "status": "PASS"},
        "description": {"value": "desc", "length": 4, "status": "PASS"},
        "h1": {"count": 1, "value": "Single H1", "status": "PASS"},
        "canonical": {"value": "https://example.com/page", "status": "PASS"},
        "flags": [],
        "human_review": False,
        "audited_at": "2026-04-01T00:00:00+00:00",
    }))]
    with mock.patch("anthropic.Anthropic") as mock_client:
        mock_client.return_value.messages.create.return_value = mock_response
        result = audit_url(snapshot, tiered=False)
        assert result["method"] == "sonnet"
        assert mock_client.return_value.messages.create.call_count == 1
    print("PASS: tiered=False → Sonnet called directly")


def test_haiku_api_failure_falls_back_to_tier1():
    """Haiku failure: falls back to Tier 1 result, no crash."""
    snapshot = make_snapshot(title="SEO")  # triggers Tier 2
    with mock.patch("anthropic.Anthropic") as mock_client:
        mock_client.return_value.messages.create.side_effect = Exception("rate limit")
        result = audit_url(snapshot, tiered=True)
        assert result["method"] == "haiku-fallback"
    print("PASS: Haiku failure → fallback to Tier 1, no crash")


if __name__ == "__main__":
    test_clean_page_returns_tier1_no_api_calls()
    test_long_title_returns_tier1_fail_no_api_call()
    test_suspiciously_short_title_escalates_to_tier2()
    test_tiered_false_calls_sonnet_directly()
    test_haiku_api_failure_falls_back_to_tier1()
    print("\nAll tests passed.")

Run it:

python test_cost_curve.py

Expected output:

PASS: clean page → Tier 1, zero API calls
PASS: title >60 → Tier 1 FAIL, zero API calls
PASS: short title → Tier 2 (Haiku called once)
PASS: tiered=False → Sonnet called directly
PASS: Haiku failure → fallback to Tier 1, no crash

Applying This Pattern to Your Agent

The cost curve is not SEO-specific. Any agent with mixed-complexity tasks can use it.

The principle: classify tasks by what they actually require before deciding which model to invoke.

Customer support agent:

• Tier 1: keyword matching for known FAQ topics — no model

• Tier 2: Haiku for intent classification on ambiguous queries

• Tier 3: Sonnet for complex complaints requiring judgment

Code review agent:

• Tier 1: lint rules, syntax checks — no model

• Tier 2: Haiku for common pattern detection

• Tier 3: Sonnet for architectural review

Content moderation agent:

• Tier 1: blocklist matching — no model

• Tier 2: Haiku for borderline cases

• Tier 3: Sonnet for context-dependent judgment

The implementation pattern is the same in all three cases. The audit_url() router becomes route_task(). The tier functions change their prompts and escalation conditions. The fallback logic stays identical.

The key question to ask before writing any agent code: what fraction of my inputs are mechanically solvable? That fraction goes to Tier 1. The rest escalate. The cost curve routes everything else.

Wrapping Up

The full implementation — including the SEO audit agent that uses this module in production — is at dannwaneri/seo-agent. The core/ directory is MIT licensed. The tiered routing lives in premium/cost_curve.py.

This tutorial is the companion piece to I Was Paying \(0.006 Per URL for SEO Audits Until I Realized Most Needed \)0 on DEV.to, which covers the architecture decisions behind the cost curve.

Most developers either rely on external tools or assume this requires backend processing. That’s usually where things get slower, more complex, and harder to maintain.

But modern browsers have quietly become powerful enough to handle this entirely on their own.

In this tutorial, you’ll build a barcode generator that runs completely in the browser. It won’t upload data anywhere, and it won’t require any server logic. Everything happens instantly on the client side.

Along the way, you’ll also learn how barcode formats work, how to validate inputs properly, and how to create a real-time preview experience that feels responsive and practical.

Table of Contents

1. How Barcode Generation Works

2. Project Setup

3. What Library Are We Using?

4. Creating the HTML Structure

5. Adding JavaScript for Barcode Generation

6. How the Barcode Is Generated

7. Types of Barcodes You Can Generate

8. Adding Real-Time Preview

9. How to Validate Input Properly

10. How to Download the Barcode

11. Important Notes from Real-World Use

12. Common Mistakes to Avoid

13. Demo: How the Barcode Generator Works

14. Conclusion

How Barcode Generation Works

A barcode is simply a visual encoding of data. Instead of displaying text directly, it represents that data using a pattern of lines and spaces.

Different barcode formats use different encoding rules. Some support only numbers, while others allow full text input. When you generate a barcode in the browser, you’re essentially converting user input into a structured visual pattern.

The key idea here is that we don’t draw these lines manually. A library takes care of encoding the data and rendering it as an SVG element, which the browser can display instantly.

Project Setup

We’ll keep this project intentionally simple so the focus stays on understanding how it works.

All you need is a basic HTML file, a small JavaScript file, and a barcode library. There’s no backend involved, and nothing gets stored or uploaded.

This makes the tool fast, private, and easy to integrate into other projects.

What Library Are We Using?

In this project, we use the JsBarcode library.

It’s a lightweight JavaScript library that can generate barcodes directly inside the browser using SVG. It supports multiple formats and works without any external dependencies.

You can include it using a CDN:

<script src="https://cdn.jsdelivr.net/npm/jsbarcode@3.11.5/dist/JsBarcode.all.min.js"></script>

Creating the HTML Structure

The interface is simple but practical. It includes an input field where users can enter data, a dropdown to choose the barcode format, and a preview area where the barcode is rendered.

<input type="text" id="text" placeholder="Enter text or number">

<select id="format">
  <option value="CODE128">Code128</option>
  <option value="EAN13">EAN13</option>
</select>

<button onclick="generateBarcode()">Generate</button>

<svg id="barcode"></svg>

This structure is enough to handle input, display output, and connect everything through JavaScript.

Adding JavaScript for Barcode Generation

Now we'll connect the user input to barcode generation.

function generateBarcode() {
  const text = document.getElementById("text").value;
  const format = document.getElementById("format").value;

  if (!text) {
    alert("Please enter a value");
    return;
  }

  JsBarcode("#barcode", text, {
    format: format,
    width: 2,
    height: 100,
    displayValue: true
  });
}

This function reads the input, checks if it exists, and then generates the barcode using the selected format.

How the Barcode Is Generated

When you call the JsBarcode function, the library handles everything behind the scenes.

It encodes the input into a barcode standard, converts that into a pattern of lines, and renders it as an SVG element. Because SVG is vector-based, the barcode remains sharp even when resized.

All of this happens instantly in the browser, which is why the experience feels fast.

Types of Barcodes You Can Generate

Different barcode formats are used in different industries, and understanding them helps you build more practical tools.

1. Code128 is the most flexible format. It supports letters, numbers, and special characters, which makes it ideal for general-purpose use.

2. EAN-13 is commonly used in retail products. It works only with 13-digit numbers, so it requires strict validation.

3. UPC is similar to EAN and is widely used in billing systems, especially in the US. It also expects numeric input with a fixed length.

4. Code39 is simpler and supports uppercase letters and numbers, but it’s less compact compared to Code128.

5. ITF-14 is mostly used in logistics and packaging. It’s designed for numeric data and is common in shipping environments.

In most cases, starting with Code128 is the safest option unless you have a specific requirement.

Adding Real-Time Preview

One of the biggest improvements you can make to a tool like this is real-time feedback.

Instead of requiring users to click a button every time, you can generate the barcode as they type.

document.getElementById("text").addEventListener("input", generateBarcode);
document.getElementById("format").addEventListener("change", generateBarcode);

This small change makes the tool feel much more responsive.

As soon as the user types or changes the format, the barcode updates automatically. This is the same kind of interaction you see in polished production tools.

How to Validate Input Properly

Validation is where many simple tools break.

Since different barcode formats have different rules, if you don’t validate input correctly, the barcode may fail silently or produce incorrect output.

Here’s a simple example:

function isValidInput(text, format) {
  if (format === "EAN13") {
    return /^\d{13}$/.test(text);
  }

  if (format === "UPC") {
    return /^\d{12}$/.test(text);
  }

  return text.length > 0;
}

Then use it inside your generator:

if (!isValidInput(text, format)) {
  alert("Invalid input for selected format");
  return;
}

This ensures users get immediate feedback instead of confusion.

How to Download the Barcode

Once the barcode is generated, you can allow users to download it.

function downloadBarcode() {
  const svg = document.getElementById("barcode");
  const serializer = new XMLSerializer();
  const source = serializer.serializeToString(svg);

  const blob = new Blob([source], { type: "image/svg+xml" });
  const url = URL.createObjectURL(blob);

  const link = document.createElement("a");
  link.href = url;
  link.download = "barcode.svg";
  link.click();
}

This converts the SVG into a file that can be downloaded directly from the browser.

Important Notes from Real-World Use

When building tools like this in production, small details matter.

Large input values can sometimes affect readability, so it’s important to test how dense the barcode becomes. Choosing the right format also makes a difference depending on whether you need flexibility or strict standards.

Another important detail is rendering quality. Using SVG instead of raster formats ensures that the barcode remains sharp even when printed.

Common Mistakes to Avoid

One common issue is skipping validation. This leads to broken or unreadable barcodes, especially with strict formats like EAN or UPC.

Another mistake is relying too much on button-based interactions. Real-time updates create a much better user experience.

Finally, developers sometimes forget to include the library correctly, which leads to silent failures. Always verify that your CDN is loaded.

Demo: How the Barcode Generator Works

To better understand how everything comes together, here’s a quick walkthrough of how the tool works in the browser.

Step 1: Select a Barcode Type

Start by choosing the barcode format. In most cases, Code128 is a good default since it supports both text and numbers.

Step 2: Enter Your Data

Next, enter the value you want to encode. This could be a product ID, URL, or any text depending on the selected format.

Step 3: Customize the Design

You can adjust things like bar width, height, and colors. These settings help control how the barcode looks and how readable it is in different use cases.

Step 4: Generate and Preview

As you type or change settings, the barcode updates instantly. This real-time preview makes it easier to experiment and see results immediately.

Step 5: Download the Barcode

Once you're satisfied with the result, you can download the barcode in formats like PNG, JPG, or SVG.

This entire process happens in the browser, without uploading any data to a server.

Conclusion

In this tutorial, you built a browser-based barcode generator using JavaScript.

More importantly, you learned how to think about building tools that run entirely on the client side. This approach reduces complexity, improves performance, and gives users a faster experience.

Once you understand this pattern, you can apply it to many other tools like QR generators, image converters, and file processors.

And that’s where things start to get interesting.

Agent skills fix this. A skill is a markdown file that loads into Claude Code's context automatically when you need it. You write the workflow once. The agent follows it every time. And because skills follow an open standard, the same file works in Claude Code, GitHub Copilot, Cursor, and Gemini CLI.

This tutorial shows you how to build a skill from scratch. You will build a commit-message-writer — a skill that reads your staged changes and generates a structured commit message following the Conventional Commits standard. By the end, you will have a working skill installed and ready to use, and you will understand the structure well enough to build any skill you need.

Table of Contents

1. What an Agent Skill Is

2. How to Choose What to Build

3. How to Structure Your Skill

4. How to Write the Description

5. How to Write the Instructions

6. How to Build the commit-message-writer Skill

7. How to Install and Test Your Skill

8. How to Improve Your Skill Over Time

9. Where to Go Next

What an Agent Skill Is

A skill is a folder containing a SKILL.md file. That file has two parts: a YAML frontmatter block at the top, and a markdown body below it.

my-skill/
└── SKILL.md

The frontmatter tells the agent what the skill is called and when to use it. The body tells the agent what to do when it loads the skill. Here is the minimal structure:

---
name: my-skill
description: What this skill does and when to use it.
---
 
# My Skill
 
Instructions for the agent go here.

When you invoke a skill — either explicitly with /skill-name or by describing what you want — the agent reads the SKILL.md body and follows the instructions inside it. The frontmatter never reaches the agent's instructions. It's metadata the skill system uses to decide whether to load the skill at all.

How the Agent Decides to Load a Skill

This is the most important thing to understand before you write your first skill: the agent decides whether to load your skill based entirely on the description field.

Skills appear in Claude Code's context as a list of names and descriptions. When you make a request, the agent scans that list and loads any skill whose description matches what you're asking for. If the description is vague, the skill won't load when you need it. If the description is too narrow, it won't load for variations of the same request.

The instructions in the body only matter after the skill loads. Getting the description right is what determines whether the skill loads at all.

What Skills Are Not

Skills are instruction files. They cannot run code on their own — but they can instruct the agent to run code using its existing tools. They are not plugins, extensions, or packages. They have no runtime. They are markdown files the agent reads, like a recipe a chef follows.

How to Choose What to Build

The best skills share three properties.

1. They encode a repeatable workflow. If you do something differently every time, a skill won't help. If you follow the same steps every session — even if you explain them differently each time — that's a skill candidate.

2. They have a clear trigger. You should be able to finish the sentence "I need this skill when I want to...". If you can't finish that sentence in one clause, the workflow isn't scoped enough for a skill.

3. They produce a consistent output format. Skills that output in a fixed structure — a commit message, a code review, a spec — are easier to build and test than skills that produce open-ended prose.

Good candidates: commit messages, pull request descriptions, code reviews, changelog entries. Bad candidates: "help me think through this", "make this better" — too open-ended to encode in a skill.

For this tutorial, commit message generation is the right scope. The trigger is obvious (you want to commit), the workflow is defined (read staged changes, apply Conventional Commits format), and the output is structured (a commit message with a specific shape).

How to Structure Your Skill

Every skill starts as a single folder with a single file:

commit-message-writer/
└── SKILL.md

As skills grow, they can include additional files the agent loads as needed:

commit-message-writer/
├── SKILL.md          ← always loaded when skill triggers
└── references/
    └── examples.md   ← loaded only when the agent needs examples

The SKILL.md body should stay under 500 lines. If your instructions are growing beyond that, move supporting detail into a references/ subfolder and tell the agent when to read those files. This keeps the skill lean — the agent only loads what it needs.

For this tutorial, a single SKILL.md is enough.

How to Write the Description

The description field is the trigger condition. It determines when your skill loads and when it doesn't. Most skills fail not because the instructions are wrong, but because the description doesn't match how people actually ask for help.

Here is a weak description:

description: Generates commit messages.

This will undertrigger. "Generate a commit message" will load it. "Write a commit for my changes" probably won't. "Summarize my staged diff" definitely won't — even though all three are asking for the same thing.

Here is a stronger description:

description: Generates structured commit messages following the Conventional Commits standard. Use when you want to commit your changes and need a well-formatted message. Triggers on "write a commit message", "commit my changes", "summarize my staged diff", "what should my commit say", or any request to describe or document code changes for version control.

The pattern is: what the skill does + when to use it + specific trigger phrases. The trigger phrases cover the different ways a developer might ask for the same thing.

Two rules for descriptions:

Be specific about the output. "Generates commit messages" is vague. "Generates structured commit messages following the Conventional Commits standard" tells the agent and the user exactly what they'll get.

Be slightly pushy. The agent has a natural tendency to undertrigger skills — to handle requests itself rather than loading a skill. A description that explicitly lists trigger phrases counteracts this. You are not being redundant. You are training the trigger.

How to Write the Instructions

The body of SKILL.md is where you define what the agent does when the skill loads. Good instructions follow two principles.

Generate first, clarify second. The agent should produce output immediately rather than asking clarifying questions. If it needs to make assumptions, it should make them and flag them — not ask. Asking questions before producing output adds friction and loses the benefit of having a skill at all.

Define the output format explicitly. Don't say "write a good commit message." Say exactly what the structure is, what fields are required, what the character limits are. The more specific the output format, the more consistent the results.

Here is what weak instructions look like:

# Commit Message Writer
 
Look at the staged changes and write a commit message that describes what changed.

That will produce different results every time — different formats, different lengths, different conventions. It's not a skill. It's a prompt.

Here is what strong instructions look like:

# Commit Message Writer
 
Read the staged diff using `git diff --staged`. Generate a commit message
following the Conventional Commits standard.
 
Output format:
type(scope): short description under 72 characters
 
Body (if changes are non-trivial):
- What changed and why, not how
- One bullet per logical change
 
Footer (if applicable):
BREAKING CHANGE: description
Closes #issue-number

The agent knows exactly what to produce. The output will be consistent across sessions, across projects, and across agents that support the standard.

How to Build the commit-message-writer Skill

Now build it. Create the skill directory:

mkdir -p ~/.claude/skills/commit-message-writer

On Windows PowerShell:

Note: PowerShell uses backtick (`) for line continuation, not backslash.

New-Item -ItemType Directory -Force -Path "$HOME\.claude\skills\commit-message-writer"

Create the SKILL.md file inside that directory. Here is the complete content:

---
name: commit-message-writer
description: Generates structured commit messages following the Conventional Commits
  standard. Use when you want to commit your changes and need a well-formatted message.
  Triggers on "write a commit message", "commit my changes", "summarize my staged
  diff", "what should my commit say", or any request to describe or document staged
  changes for version control.
---
 
# commit-message-writer
 
You generate structured commit messages from staged git changes.
 
## How to invoke
 
Run `git diff --staged` to read the staged changes. If nothing is staged, tell the
user and suggest they run `git add` first.
 
Generate first. Do not ask clarifying questions before producing the commit message.
If you need to make assumptions about scope or type, make them and note them after
the output.
 
## Output format
 
~~~
type(scope): short description
 
[body — optional, include if changes are non-trivial]
 
[footer — optional]
~~~
 
**Type** — choose one:
- `feat` — a new feature
- `fix` — a bug fix
- `docs` — documentation changes only
- `refactor` — code change that neither fixes a bug nor adds a feature
- `test` — adding or updating tests
- `chore` — build process, tooling, or dependency updates
 
**Scope** — the module, file, or area affected. Use the directory name or component
name. Omit if the change spans the entire codebase.
 
**Short description** — imperative mood, under 72 characters, no period at the end.
"Add user authentication" not "Added user authentication" or "Adds user authentication."
 
**Body** — what changed and why, not how. One bullet per logical change. Skip if the
short description is self-explanatory.
 
**Footer** — include `BREAKING CHANGE:` if the commit breaks backward compatibility.
Include `Closes #N` if it resolves a GitHub issue.
 
## Quality rules
 
- Never use "updated", "changed", or "modified" in the short description — be specific
- Never write "various improvements" or "misc fixes" — name what improved
- If more than three files changed across unrelated concerns, flag it:
  "These changes may be better split into separate commits: [list concerns]"
- The short description must be under 72 characters — count before outputting
 
## Example output
 
Input: staged changes adding a rate limiter to an API endpoint
 
~~~
feat(api): add rate limiting to /query endpoint
 
- Limits requests to 100 per minute per IP using Cloudflare's rate limit binding
- Returns 429 with Retry-After header when limit is exceeded
- Adds rate limit configuration to wrangler.toml
 
Closes #47
~~~

Save that file. The skill is built.

How to Install and Test Your Skill

Verify the File Exists

cat ~/.claude/skills/commit-message-writer/SKILL.md

You should see the full SKILL.md content. If you get an error, check the directory path.

Test the Skill

Open Claude Code in any git repository that has staged changes. Type:

/commit-message-writer

The agent will read your staged diff and produce a commit message following the format you defined.

You can also trigger it naturally:

write a commit message for my staged changes

what should my commit say

summarize my diff for git

All three should load the skill and produce a structured commit message. If the skill doesn't trigger on natural language requests, the description needs more trigger phrases — see the improvement section below.

Test Edge Cases

Test these cases before relying on the skill in production:

# Stage nothing, then ask for a commit message
git add -p  # stage nothing
# In Claude Code: "write a commit message"
# Expected: skill tells you nothing is staged and suggests git add

# Stage changes across unrelated files
git add src/api.ts src/styles.css README.md
# In Claude Code: "write a commit message"  
# Expected: skill flags that commits may be better split

How to Improve Your Skill Over Time

The first version of any skill is a draft. You improve it by observing where it produces inconsistent or wrong output, then updating the instructions.

When the Skill Undertriggers

If you type "summarize my changes for git" and the skill doesn't load, add that phrase to the description's trigger list:

description: ... Triggers on "write a commit message", "commit my changes",
  "summarize my staged diff", "summarize my changes for git", ...

The description is your primary lever for fixing triggering problems.

When the Output Format Drifts

If the agent starts producing commit messages that don't match your format — wrong type, missing scope, body in the wrong style — the instructions need to be more explicit. Add a concrete example that shows the failure and the correct output:

## Common mistakes to avoid
 
Wrong: "Updated the authentication flow"
Right: "refactor(auth): simplify token validation logic"
 
Wrong: "Fixed bugs"
Right: "fix(api): handle null response from upstream service"

Concrete counterexamples are more effective than abstract rules.

When the Scope Grows

If you find yourself wanting the skill to handle related tasks — reviewing commit messages, generating changelogs, writing PR descriptions — resist the urge to add everything to one skill. Build separate skills. Each skill should do one thing well. The Agent Skills standard is designed for composition, not for monolithic instructions.

Where to Go Next

The commit-message-writer covers the core pattern. The same structure works for any repeatable workflow.

Pull request descriptions follow the same shape — read the diff, apply a structure, produce consistent output. The trigger phrases are different ("write a PR description", "summarize my branch for review") and the output format adds sections for motivation and testing, but the SKILL.md structure is identical.

Code review checklists work well as skills when your team has a standard review process. The trigger is "review this code" or "check this PR", and the instructions encode whatever your team actually checks — security concerns, test coverage, naming conventions.

The commit-message-writer is the simplest skill architecture — instructions only. As your skills grow more specialized, two other patterns become useful.

The first adds a references/ directory: the voice-humanizer skill loads a CORPUS.md file containing the author's published writing, which the agent reads when it needs to check output against a specific style. The second adds quality rules and structured output formats that make results stricter and more consistent — that's the pattern spec-writer uses to surface assumptions inline. Each is the same SKILL.md structure at a different level of complexity.

Start with instructions only. Add references when the agent needs external context. Add output format rules when consistency matters more than flexibility.

The Agent Skills standard is supported in Claude Code, GitHub Copilot in VS Code, Cursor, and Gemini CLI. A skill you build once installs across all of them. The install path differs by agent:

The SKILL.md format is the same across all of them.

The commit-message-writer you just built is a working skill. The next one will take less time. By the third, you will start seeing workflows you repeat and immediately think: that should be a skill.

That's the point.

The tool is spec-writer: a Claude Code skill that takes a vague feature request and generates a structured spec, technical plan, and task breakdown before a single line of code gets written.

The problem it solves is one most developers hit within their first week of using AI coding agents seriously: the agent writes confidently in the wrong direction and you pay for it twice, once in tokens, once in rewrites.

This tutorial shows you how to install spec-writer, how to invoke it on a real feature, and how to read the output so you can catch the assumptions that would have wasted your time.

Table of Contents

1. The Problem with Prompting Agents Directly

2. What Spec-Driven Development Is

3. How spec-writer Works

4. How to Install spec-writer

5. How to Write Your First Spec

6. How to Read the Output

7. How to Hand the Spec to Your Agent

8. Where to Go Next

The Problem with Prompting Agents Directly

Here is what happens when you skip the spec.

You have a feature in your head: "Add a way for users to export their data." You open Claude Code and describe it. The agent produces code. It looks right. You run it. It's mostly right – except it exports everything including soft-deleted records, it doesn't paginate, it times out on large accounts, and it has no authentication check on the export endpoint.

None of those things were in your prompt. The agent guessed, and it guessed plausibly – which is worse than guessing obviously wrong. You didn't notice until testing.

This is the fundamental problem with prompting agents directly on anything non-trivial: your prompt carries your conscious requirements, but every feature has a shadow of requirements you didn't think to state. And the agent fills that shadow with assumptions.

Most of the time, those assumptions are reasonable. Some of the time, they're wrong in ways that take hours to unravel.

The failure mode isn't hallucination. It's the agent being exactly as helpful as the prompt allowed, which wasn't helpful enough.

Spec-Driven Development addresses this directly. The methodology – documented extensively by practitioners like Julián Deangelis – argues that a written spec isn't documentation overhead. It's the mechanism that forces you to make decisions before the agent does.

What Spec-Driven Development Is

Spec-Driven Development is the practice of writing a structured specification before you write code or prompt an agent. The spec defines what the feature must do, what assumptions are being made, and what tasks the implementation breaks into.

The key insight is what a spec is for. A spec is not trying to replace code. It's trying to surface the decisions that would otherwise be invisible. The agent will make those decisions either way: with a spec, you make them first. Without a spec, you discover them during testing.

The strongest counterargument to SDD comes from Gabriella Gonzalez: a sufficiently detailed spec is just code. She's right that some specs devolve into pseudocode so specific they might as well be implementations.

But that's a spec written at the wrong level of abstraction. The goal is to name the decisions, not to pre-implement them. "Only authenticated users can trigger this export" is a decision. "Call verifyJWT(token) and return 401 if it fails" is implementation. The spec needs the first. The agent handles the second.

SDD has three levels:

1. Spec-First: write a spec before every feature and hand it to the agent as context. This is the entry point and the workflow this tutorial focuses on.

2. Spec-Anchored: the spec lives in the repository and evolves alongside the code. When requirements change, you update the spec and re-prompt the agent to realign.

3. Spec-as-Source: the spec is the primary artifact. Code is generated from it and considered disposable. This is the most ambitious level and the direction many teams are moving toward.

spec-writer gets you to Spec-First immediately, with no ceremony.

How spec-writer Works

spec-writer is a Claude Code skill – a markdown file that loads into the agent's context and changes how it responds when invoked.

The skill follows one rule: generate first, flag assumptions inline. Instead of asking you clarifying questions before producing output, it generates the full spec immediately and marks every decision it made without your explicit input using [ASSUMPTION: ...] tags. Then you correct what's wrong.

This is faster than Q&A because it makes the decisions visible in a form you can react to rather than anticipate.

The output has three sections in fixed order:

1. SPEC: the what. One-line purpose, user stories, requirements, edge cases, and acceptance criteria in Given/When/Then format.

2. PLAN: the how. Stack and architecture decisions, data model changes, API contracts, testing strategy, and security constraints.

3. TASKS: the breakdown. Ordered, self-contained tasks each completable in a single agent session, each with its own acceptance criteria.

After the three sections, the skill produces an Assumptions summary: every [ASSUMPTION: ...] from the output, ranked by impact. This is the part you review before handing anything to the agent.

The skill is compatible with GitHub Spec Kit and OpenSpec. If you use either framework, save the spec output to your .specify/ or openspec/changes/ directory and continue from there.

How to Install spec-writer

spec-writer uses the Agent Skills standard, which means the same SKILL.md file works across Claude Code, Cursor, GitHub Copilot, Gemini CLI, and any other agent that supports the standard. You install it once and it works everywhere.

Installation

Create the skills directory if it doesn't exist and clone the repo:

mkdir -p ~/.claude/skills
git clone https://github.com/dannwaneri/spec-writer.git ~/.claude/skills/spec-writer

On Windows PowerShell:

(Note: PowerShell uses backtick (`) for line continuation, not backslash.)

New-Item -ItemType Directory -Force -Path "$HOME\.claude\skills"
git clone https://github.com/dannwaneri/spec-writer.git "$HOME\.claude\skills\spec-writer"

That's the entire installation. No package to install, no configuration file to edit, no API key. The skill is a markdown file. The agent reads it.

Verification

Open Claude Code and type:

/spec-writer test

If the skill is installed correctly, the agent will read the SKILL.md and produce a spec structure – even for "test" as input. You'll see the three sections and the Assumptions summary. If nothing happens, confirm that the ~/.claude/skills/spec-writer/SKILL.md file exists.

How to Write Your First Spec

The invocation pattern is:

/spec-writer [your feature description]

The description can be as rough as you'd write in a Slack message. The skill's job is to structure it. You don't need to be precise. Being precise is what the spec is for.

A Real Example

Here is a real invocation from the Foundation project, a federated knowledge base built on Cloudflare Workers:

/spec-writer Add CLI capture for Claude Code sessions stored in ~/.claude/projects/

That's twelve words. No mention of the tech stack, no data model details, no authentication requirements, no error handling spec. All of that comes out in the spec.

Here is the abbreviated output:

SPEC

One-line purpose: Developers can capture Claude Code session logs from their local filesystem into Foundation before they are deleted after 30 days.

Users and use cases:

• As a developer using Claude Code daily, I want my coding sessions captured automatically so that architectural decisions and debugging patterns don't disappear after 30 days.

• As a Foundation user, I want CLI sessions and browser extension captures in the same knowledge base so that I have one place to query across all my AI interactions.

Acceptance criteria:

Given a developer with Claude Code sessions in ~/.claude/projects/
When they run the Foundation CLI capture command
Then a list of uncaptured sessions is displayed, sorted by most recent first
 
Given a session already in Foundation
When the developer runs capture again
Then that session does not appear in the review list
 
Given a malformed .jsonl file
When the capture command processes it
Then an error is logged for that file and processing continues on remaining sessions

PLAN

Stack and architecture:

CLI capture runs locally — it needs to read the local filesystem, which
Cloudflare Workers cannot do. [ASSUMPTION: CLI capture is a local Node.js
or Bun script that calls the Foundation API to insert sessions, rather
than a Worker itself]

API contracts:

• POST /api/sessions/import – accepts parsed session JSON, returns session ID

• Returns 409 if session already exists

• Triggers evaluator pipeline after successful insert

TASKS

## Task 1: .jsonl parser
 
**What to build:** A parser that reads a Claude Code .jsonl session file
and outputs Foundation's internal message format.
**Files likely affected:** cli/src/parsers/claudeCode.js (create)
**Acceptance criteria:**
1. Parses a valid .jsonl file into the correct message format
2. Handles malformed lines without crashing — logs and skips
3. Returns empty array for empty file
**Dependencies:** none

Assumptions to review:

1. CLI capture is a local script calling the Foundation API, not a Worker
   Impact: HIGH
   Correct this if: you want a purely serverless approach
 
2. Manual curation before capture, not automatic bulk import
   Impact: HIGH
   Correct this if: you want automatic background capture
 
3. Session ID from .jsonl filename is the deduplication key
   Impact: MEDIUM
   Correct this if: session IDs are stored differently in your schema
 
4. No sensitive data scrubbing in v1
   Impact: MEDIUM
   Correct this if: your sessions contain credentials or keys

Twelve words in, four decisions surfaced immediately – three of which had real architectural implications.

The third assumption ("Session ID from .jsonl filename is the deduplication key") is the one that would have caused the most subtle bug. The agent would have implemented deduplication based on the filename and it would have worked until a session was renamed. The spec caught it before a line of code was written.

How to Read the Output

The output is designed to be scanned for [ASSUMPTION: ...] tags first, read for the tasks second.

Reading the Assumptions

Every [ASSUMPTION: ...] tag marks a place where the agent filled in something you didn't specify. Your job is to go through the Assumptions summary and decide for each one:

• Correct: the assumption is right, leave it

• Override: the assumption is wrong, restate it and re-run the spec

• Defer: the assumption doesn't matter for this iteration, mark it and move on

The impact rating tells you which assumptions to fix before you start coding. HIGH-impact assumptions affect architecture or data model. If they're wrong, fixing them requires rework. LOW-impact assumptions affect behavior details that are easy to change later.

Reading the Acceptance Criteria

The acceptance criteria in Given/When/Then format are the most useful part of the spec for catching scope errors. Read each one and ask: is this actually what I want?

Criteria are binary by design. "Returns 401 when unauthenticated" is a criterion. "Works correctly" is not. If you find yourself reading a criterion and thinking "well, it depends", then that's a signal that the criterion is hiding an assumption. Restate it.

Reading the Tasks

The tasks are ordered and self-contained. Each task produces a verifiable change. Before you hand any task to an agent, check two things:

1. Does the task have all the context it needs? If a task says "follow the existing auth pattern" and you haven't pointed the agent at your auth code, it will guess.

2. Does the acceptance criteria match what you'd actually test? If the criteria are vague, tighten them before the agent sees the task.

How to Hand the Spec to Your Agent

The spec is context, not a prompt. When you start an agent session for a task, include the relevant spec sections alongside the task description.

For Task 1 from the example above, your agent session might open like this:

Context:
- This is a federated knowledge base built on Cloudflare Workers, D1, and Vectorize
- Sessions are stored in ~/.claude/projects/ as .jsonl files
- The API runs at https://<your-worker>.workers.dev
 
Spec:
[paste the SPEC and PLAN sections]
 
Task:
[paste Task 1]

The context block is just an example. Replace it with your own project's tech stack, file locations, and API URL. The point is to give the agent the same context a new team member would need on day one.

The agent now has requirements, architecture context, and a single scoped task with binary acceptance criteria. It cannot guess the deduplication key incorrectly because the spec already resolved that assumption. It cannot skip error handling because the acceptance criteria explicitly require it.

This is the workflow the spec is designed for. The spec doesn't replace the agent. Rather, it removes the decisions from the agent's hands and puts them in yours, before the work starts.

Saving the Spec for Later

If you want to move toward Spec-Anchored development – where the spec lives in the repository – save the output to a specs/ directory in your project:

# Create specs directory
mkdir -p specs
 
# Save your spec
# Paste the output into specs/cli-capture.md

When requirements change, update the spec and re-prompt the agent to realign the implementation. The spec becomes the source of truth, not the code comments.

Where to Go Next

Try it on your next feature before you write a line of code. The assumptions it flags will tell you something about your feature you hadn't consciously decided yet – and correcting the HIGH-impact ones before you hand anything to an agent is the whole point. Skipping that step is the same as prompting directly.

If your project is growing, move toward Spec-Anchored. Save specs in your repository under specs/. When a new contributor joins or an agent starts a session cold, the specs give them the decisions that got made without requiring them to reverse-engineer the code.

The strongest ongoing challenge to this workflow is Gabriella Gonzalez's argument that detailed specs become code. If your specs are getting implementation-specific, you've crossed a line. Pull back to decisions – "only authenticated users can trigger this" – and leave implementation to the agent. The spec's job is to name what the agent would have guessed wrong, not to write the feature in prose.

The Agent Skills standard now works across Claude Code, GitHub Copilot, Cursor, and Gemini CLI. The spec-writer repo is at github.com/dannwaneri/spec-writer.

The irony of spending 64% of a Claude budget building a token-efficiency tool is real. But the spec surfaced four decisions on a twelve-word prompt. The fourth one – the deduplication key assumption – would have produced a bug that worked perfectly until a session got renamed.

That's not a hallucination. That's the agent being exactly as helpful as the prompt allowed.

The spec is how you raise the ceiling on what "helpful" means.

This tutorial is different. I run a production RAG system (vectorize-mcp-worker) that handles real traffic at a total cost of \(5/month. The alternatives I evaluated ranged from \)100–$200/month. The difference isn't magic. It's architecture.

Here, you'll build rag-tutorial-simple: a clean, minimal RAG chatbot deployed on Cloudflare Workers. No external API keys. No paid vector database subscriptions. No servers to manage. Just Cloudflare's free tier – Workers, Vectorize, and Workers AI – doing the heavy lifting at the edge.

Table of Contents

1. What You Will Build

2. Prerequisites

3. How RAG Works

4. How to Set Up Your Project

5. How to Build the Data Pipeline

6. How to Build the Query Pipeline

7. How to Add Error Handling and Security

8. Performance and Cost Analysis

9. Conclusion

What You Will Build

By the end of this tutorial, you'll have a globally deployed RAG API that:

• Accepts a natural language question via HTTP

• Converts it to a vector embedding using Workers AI

• Searches a knowledge base stored in Cloudflare Vectorize

• Passes the retrieved context to an LLM (also on Workers AI) to generate an answer

• Returns a grounded, accurate response (not a hallucination)

The complete source code is available at github.com/dannwaneri/rag-tutorial-simple.

Prerequisites

This is an intermediate-level tutorial. You should be comfortable with:

• JavaScript/TypeScript: async/await, promises, basic types

• HTTP APIs: REST, request/response, JSON

• Command line basics: running npm commands, navigating directories

You will need:

• Node.js 18 or higher: check with node --version

• A Cloudflare account: free tier is fine, sign up at cloudflare.com

• A code editor: VS Code recommended for TypeScript support

That's it. No OpenAI key. No credit card for embeddings. Let's build.

How RAG Works

Before you write any code, you'll need a clear mental model of what you're building. This section explains the three core components of a RAG system, how data flows between them, and why this architecture works at scale.

The Mental Model

Think of a traditional LLM like a doctor who studied medicine for years but has been in a remote cabin with no internet since their graduation day. They are brilliant, but they only know what they knew when they left. Ask them about a drug approved last year and they'll either say they don't know or – worse – confidently give you wrong information.

RAG gives that doctor access to an up-to-date medical library. Before answering your question, they can look up the relevant pages, read them, and use that information to give you an accurate answer. Their training still matters (that is, they know how to read and interpret the information), but they're no longer limited to what they memorized years ago.

In technical terms, RAG works in three steps on every request:

1. Retrieve: find the most relevant documents from your knowledge base

2. Augment: add those documents to the LLM prompt as context

3. Generate: let the LLM produce an answer using both its training and the retrieved context

The Three Components

Every RAG system has three moving parts. Understanding each one will help you debug problems and make better architectural decisions as you build.

The Embedding Model

An embedding model converts text into a vector – an array of numbers that represents the meaning of that text. The model you will use in this tutorial, @cf/baai/bge-base-en-v1.5, outputs 768 numbers for any piece of text you give it.

The critical property of embeddings is that semantically similar text produces numerically similar vectors. "How do I install Node.js?" and "What's the process for setting up Node?" will produce vectors that are close together. "How do I install Node.js?" and "What is the capital of France?" will produce vectors that are far apart.

This is what makes semantic search possible. You aren't matching keywords, you're matching meaning.

One rule you must never break: your documents and your queries must be embedded with the same model. If you embed your documents with bge-base-en-v1.5 and your queries with a different model, the vectors won't be comparable and your searches will return garbage.

The Vector Database

The vector database stores your embeddings and lets you search them by similarity. In this tutorial, you'll use Cloudflare Vectorize.

When you run a similarity search, you pass in a query vector and Vectorize returns the K most similar vectors it has stored, along with their metadata and similarity scores. This is called approximate nearest neighbor search, and Vectorize is optimized to do it fast even across millions of vectors.

The key advantage of using Vectorize over an external vector database like Pinecone is co-location. Vectorize runs in the same Cloudflare network as your Worker. There's no external API call, no authentication roundtrip, and no network latency between your application and your database.

The Language Model

The LLM is responsible for one thing: reading the retrieved context and generating a natural language answer. It doesn't search anything. It doesn't decide what's relevant. It just reads what you give it and writes a response.

This separation of concerns is intentional. The LLM is good at language: understanding questions, synthesizing information, writing clearly. The vector database is good at retrieval: finding relevant documents fast. RAG combines their strengths without asking either component to do something it is not designed for.

In this tutorial you'll use @cf/meta/llama-3.3-70b-instruct-fp8-fast through Workers AI. No API key required.

A Note on Visual Embeddings

If you plan to extend this system to search images, you may be tempted to use a vision-language model like CLIP to generate visual embeddings (vectors that represent the image itself rather than a text description of it). This sounds clever but works worse for RAG in practice.

Visual embeddings match pixel similarity. They are good for "find images that look like this one." They are poor for "find the login screen" or "find dashboards showing error rates" because those queries are about meaning, not pixels.

The better approach – used in production – is to pass the image through a multimodal model like Llama 4 Scout, which generates a detailed text description and extracts visible text via OCR. You then embed that description using the same BGE model as your other documents.

The result lives in one unified index, works with your existing query pipeline, and produces better search results than visual embeddings for RAG use cases.

Cloudflare Workers AI does not support CLIP anyway. But even if it did, descriptions would outperform it for semantic search.

How a Query Flows Through the System

Here is exactly what happens when a user sends the question "What is RAG?" to your finished Worker:

1. Step 1 – Embed the question (20-30ms): Your Worker calls Workers AI with the question text. The embedding model returns a 768-dimensional vector representing the meaning of the question.

2. Step 2 – Search Vectorize (30-50ms): Your Worker passes that vector to Vectorize, which searches your knowledge base and returns the 3 most similar documents with their similarity scores.

3. Step 3 – Filter and build context (< 1ms): Documents with a similarity score below 0.5 are discarded. The remaining document texts are joined into a context string.

4. Step 4 – Generate the answer (500-1500ms): Your Worker sends the context and the question to the LLM. The LLM reads the context and generates a grounded answer.

5. Step 5 – Return to the user: The answer and source metadata are returned as JSON.

Total time: typically 600-1600ms end to end. The LLM generation step dominates. Everything else is fast.

Why This Works at Scale

A common objection to Cloudflare RAG is that it cannot meet sub-200ms retrieval requirements. That objection comes from a specific architectural mistake: trying to run the entire RAG pipeline, including heavy embedding generation and reranking, inside a single synchronous request. That's the wrong architecture.

The architecture you're building in this tutorial separates the loading step (which is slow and runs once) from the query step (which is fast and runs on every request). By the time a user asks a question, your documents are already embedded and stored. The query pipeline only needs to embed the question, run one vector search, and call the LLM. Those three steps are fast.

My production system (vectorize-mcp-worker) runs this architecture and handles real traffic at $5/month. The full performance breakdown is here. Cloudflare RAG works. You just have to build it correctly.

How to Set Up Your Project

In this section, you'll scaffold a Cloudflare Worker, create a Vectorize index to store your embeddings, and configure the bindings that connect them together.

How to Create the Project

Open your terminal and create a new directory for the project.

On Mac/Linux:

mkdir rag-tutorial-simple && cd rag-tutorial-simple

On Windows PowerShell:

mkdir rag-tutorial-simple
cd rag-tutorial-simple

Then run the Cloudflare scaffolding tool:

npm create cloudflare@latest

Answer the prompts like this:

• Directory/app name: rag-tutorial-simple

• What would you like to start with? Hello World example

• TypeScript? Yes

• Deploy? No

When it finishes, you'll have a working TypeScript Worker with Wrangler already configured.

How to Create the Vectorize Index

Vectorize is Cloudflare's vector database. It lives in the same network as your Worker, which means no external API call and no added latency when you search it.

npx wrangler vectorize create rag-tutorial-index --dimensions=768 --metric=cosine

Two things to note here.

--dimensions=768 tells Vectorize how many numbers make up each embedding. This must match the output of the embedding model you use. The model you will use (@cf/baai/bge-base-en-v1.5) outputs 768 dimensions. If this number doesn't match, your searches will fail.

--metric=cosine is how Vectorize measures similarity between vectors. Cosine similarity measures the angle between two vectors rather than the distance between them. For text embeddings, this captures semantic meaning more accurately than other metrics.

How to Configure wrangler.toml

Open wrangler.toml and replace its contents with the following:

name = "rag-tutorial-simple"
main = "src/index.ts"
compatibility_date = "2026-02-25"

[[vectorize]]
binding = "VECTORIZE"
index_name = "rag-tutorial-index"

[ai]
binding = "AI"

The [[vectorize]] block connects your Worker to the index you just created. The [ai] block gives your Worker access to Workers AI – both for generating embeddings and for running the language model that produces answers.

Notice that there are no API keys anywhere. Cloudflare handles authentication internally because everything – your Worker, Vectorize, and Workers AI – runs under the same account.

How to Update src/index.ts

Open src/index.ts and replace the generated code with this:

export interface Env {
  VECTORIZE: VectorizeIndex;
  AI: Ai;
  LOAD_SECRET: string;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    return new Response("RAG tutorial worker is running", { status: 200 });
  },
};

The Env interface tells TypeScript what bindings are available inside your Worker. VectorizeIndex and Ai are types provided by Cloudflare's type definitions.

How to Verify Your Setup

Start the local development server:

npx wrangler dev

Open your browser and visit http://localhost:8787. You should see:

RAG tutorial worker is running

You will see two warnings in your terminal. Both are expected.

The first warning says that Vectorize doesn't support local mode. This means Vectorize queries won't work during local development unless you run with the --remote flag. You'll do this later when testing the full pipeline.

The second warning says the AI binding always accesses remote resources. This means that embedding generation and LLM calls always hit Cloudflare's servers, even in local development. This is fine: usage within the free tier limits costs nothing.

Your project structure at this point:

rag-tutorial-simple/
├── scripts/
│   └── knowledge-base.ts
├── src/
│   └── index.ts
├── wrangler.toml
├── package.json
└── tsconfig.json

How to Build the Data Pipeline

The data pipeline is responsible for two things: generating embeddings for each document in your knowledge base, and storing those embeddings in Vectorize. You'll handle both steps inside the Worker itself using a /load endpoint.

This approach has a key advantage: you don't need an API token, an Account ID, or any external tooling. Everything uses the bindings you already configured in wrangler.toml.

How to Create the Knowledge Base

Create a scripts/ folder in your project and add a file called knowledge-base.ts:

mkdir scripts

Add your documents to scripts/knowledge-base.ts:

export const documents = [
  {
    id: "1",
    text: "Cloudflare Workers run JavaScript at the edge, in over 300 data centers worldwide. Requests are handled close to the user, reducing latency significantly compared to a single-region server.",
    metadata: { source: "cloudflare-docs", category: "workers" },
  },
  {
    id: "2",
    text: "Vectorize is Cloudflare's vector database. It stores embeddings and lets you search them by semantic similarity. It runs in the same network as your Worker, so there is no external API call needed.",
    metadata: { source: "cloudflare-docs", category: "vectorize" },
  },
  {
    id: "3",
    text: "Workers AI lets you run machine learning models directly on Cloudflare's infrastructure. You can generate embeddings and run LLM inference without leaving the Cloudflare network.",
    metadata: { source: "cloudflare-docs", category: "workers-ai" },
  },
  {
    id: "4",
    text: "RAG stands for Retrieval Augmented Generation. Instead of relying only on what the LLM was trained on, RAG retrieves relevant context from a knowledge base and adds it to the prompt before generating an answer.",
    metadata: { source: "ai-concepts", category: "rag" },
  },
  {
    id: "5",
    text: "An embedding is a numerical representation of text. Similar pieces of text produce similar embeddings. This is what makes semantic search possible — you search by meaning, not exact keywords.",
    metadata: { source: "ai-concepts", category: "embeddings" },
  },
  {
    id: "6",
    text: "The BGE model (bge-base-en-v1.5) is available through Workers AI. It generates 768-dimensional embeddings and works well for English semantic search tasks.",
    metadata: { source: "cloudflare-docs", category: "workers-ai" },
  },
  {
    id: "7",
    text: "Cosine similarity measures the angle between two vectors. For text embeddings, it captures semantic similarity regardless of text length, which makes it more reliable than Euclidean distance.",
    metadata: { source: "ai-concepts", category: "embeddings" },
  },
  {
    id: "8",
    text: "Cloudflare Workers have a free tier that includes 100,000 requests per day. Vectorize is available on both the Workers Free and Paid plans. The free tier lets you prototype and experiment. The Workers Paid plan starts at $5/month and includes higher usage allocations for production workloads.",
    metadata: { source: "cloudflare-docs", category: "pricing" },
  },
];

Each document has three fields. The id is a unique string that Vectorize uses to identify the vector. The text is what gets converted into an embedding. The metadata is stored alongside the vector and returned in search results. You'll use it later to display the source of each answer.

Understanding Embeddings

Before writing the loading code, it helps to understand what you're actually generating.

An embedding is an array of 768 numbers that represents the meaning of a piece of text. The model reads a sentence and outputs those 768 numbers in a way where similar sentences produce similar arrays of numbers.

When a user asks a question, you convert that question into an embedding using the same model, then ask Vectorize to find the stored embeddings that are closest to it. The documents those embeddings came from are your most relevant context.

This is why the model choice matters: your documents and your queries must be embedded with the same model, or the similarity scores will be meaningless.

How to Build the Load Endpoint

Open src/index.ts and update it with a /load route. Here is the complete file at this stage:

import { documents } from "../scripts/knowledge-base";

export interface Env {
  VECTORIZE: VectorizeIndex;
  AI: Ai;
  LOAD_SECRET: string;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url);

    if (url.pathname === "/load" && request.method === "POST") {
      return handleLoad(env, request);
    }

    return new Response("RAG tutorial worker is running", { status: 200 });
  },
};

async function handleLoad(env: Env, request: Request): Promise<Response> {
  const authHeader = request.headers.get("X-Load-Secret");
  if (authHeader !== env.LOAD_SECRET) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const results: { id: string; status: string }[] = [];

  for (const doc of documents) {
    const response = await env.AI.run("@cf/baai/bge-base-en-v1.5", {
      text: [doc.text],
    }) as { data: number[][] };

    await env.VECTORIZE.upsert([
      {
        id: doc.id,
        values: response.data[0],
        metadata: {
          ...doc.metadata,
          text: doc.text,
        },
      },
    ]);

    results.push({ id: doc.id, status: "loaded" });
  }

  return Response.json({ success: true, loaded: results });
}

Notice that env.AI.run() and env.VECTORIZE.upsert() require no credentials. The bindings handle authentication because the Worker runs inside your Cloudflare account. There are no secrets to manage for internal service communication.

The text: doc.text field inside metadata is important. Vectorize stores the vector values and whatever metadata you provide, but it doesn't store the original text separately. By including the text in metadata, you can retrieve and display it in search results later.

The as { data: number[][] } cast is necessary because the TypeScript type definitions for Workers AI do not yet reflect the exact return shape of every model. The actual response always contains a data array, and the cast tells TypeScript to trust that.

How to Deploy and Load Your Knowledge Base

First, set the secret that will protect your load endpoint:

npx wrangler secret put LOAD_SECRET

Type a strong value when prompted. Then deploy:

npx wrangler deploy

Trigger the load endpoint. You only need to do this once, or any time you update your knowledge base:

curl -X POST https://rag-tutorial-simple.<your-subdomain>.workers.dev/load \
  -H "X-Load-Secret: your-secret-value"

On Windows PowerShell:

Note: PowerShell uses backtick (`) for line continuation, not backslash.

Invoke-WebRequest `
  -Uri "https://rag-tutorial-simple.<your-subdomain>.workers.dev/load" `
  -Method POST `
  -Headers @{"X-Load-Secret"="your-secret-value"} `
  -UseBasicParsing

You should see:

{
  "success": true,
  "loaded": [
    { "id": "1", "status": "loaded" },
    { "id": "2", "status": "loaded" },
    { "id": "3", "status": "loaded" },
    { "id": "4", "status": "loaded" },
    { "id": "5", "status": "loaded" },
    { "id": "6", "status": "loaded" },
    { "id": "7", "status": "loaded" },
    { "id": "8", "status": "loaded" }
  ]
}

Your knowledge base is now stored in Vectorize as vectors. In the next section, you'll build the query pipeline that searches those vectors and generates answers.

How to Build the Query Pipeline

The query pipeline is the core of your RAG system. When a user sends a question, the pipeline runs four steps in sequence: embed the question, search Vectorize, build context from the results, and generate an answer with the LLM.

Add a /query route to your fetch handler and the complete handleQuery function. Here is the full updated src/index.ts:

import { documents } from "../scripts/knowledge-base";

export interface Env {
  VECTORIZE: VectorizeIndex;
  AI: Ai;
  LOAD_SECRET: string;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url);

    if (url.pathname === "/load" && request.method === "POST") {
      return handleLoad(env, request);
    }

    if (url.pathname === "/query" && request.method === "POST") {
      return handleQuery(request, env);
    }

    return new Response("RAG tutorial worker is running", { status: 200 });
  },
};

async function handleLoad(env: Env, request: Request): Promise<Response> {
  const authHeader = request.headers.get("X-Load-Secret");
  if (authHeader !== env.LOAD_SECRET) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  const results: { id: string; status: string }[] = [];

  for (const doc of documents) {
    const response = await env.AI.run("@cf/baai/bge-base-en-v1.5", {
      text: [doc.text],
    }) as { data: number[][] };

    await env.VECTORIZE.upsert([
      {
        id: doc.id,
        values: response.data[0],
        metadata: {
          ...doc.metadata,
          text: doc.text,
        },
      },
    ]);

    results.push({ id: doc.id, status: "loaded" });
  }

  return Response.json({ success: true, loaded: results });
}

async function handleQuery(request: Request, env: Env): Promise<Response> {
  const body = await request.json() as { question: string };

  if (!body.question) {
    return Response.json({ error: "question is required" }, { status: 400 });
  }

  // Step 1: Embed the question using the same model as your documents
  const embeddingResponse = await env.AI.run("@cf/baai/bge-base-en-v1.5", {
    text: [body.question],
  }) as { data: number[][] };

  // Step 2: Search Vectorize for the 3 most similar documents
  const searchResults = await env.VECTORIZE.query(
    embeddingResponse.data[0],
    {
      topK: 3,
      returnMetadata: "all",
    }
  );

  // Step 3: Build context from results above the similarity threshold
  const context = searchResults.matches
    .filter((match) => match.score > 0.5)
    .map((match) => match.metadata?.text as string)
    .filter(Boolean)
    .join("\n\n");

  if (!context) {
    return Response.json({
      answer: "I could not find relevant information to answer that question.",
      sources: [],
    });
  }

  // Step 4: Generate an answer using the retrieved context
  const aiResponse = await env.AI.run("@cf/meta/llama-3.3-70b-instruct-fp8-fast", {
    messages: [
      {
        role: "system",
        content: "You are a helpful assistant. Answer the question using only the context provided. If the context does not contain enough information, say so.",
      },
      {
        role: "user",
        content: `Context:\n\({context}\n\nQuestion: \){body.question}`,
      },
    ],
    max_tokens: 256,
  }) as { response: string };

  // Step 5: Return the answer with its sources
  const sources = searchResults.matches
    .filter((match) => match.score > 0.5)
    .map((match) => match.metadata?.source as string)
    .filter(Boolean);

  return Response.json({
    answer: aiResponse.response,
    sources: [...new Set(sources)],
  });
}

What each step does:

1. Step 1 – Embed the question: You convert the user's question into a 768-dimensional vector using the same model you used when loading your documents. This is critical: the question and the documents must be embedded with the same model or the similarity scores will be meaningless.

2. Step 2 – Search Vectorize: You pass the question embedding to Vectorize, which returns the three most similar documents. returnMetadata: "all" tells Vectorize to include the metadata you stored alongside each vector — including the original text.

3. Step 3 – Build context: You filter out any results with a similarity score below 0.5 and join the remaining document texts into a single context string. The 0.5 threshold prevents the LLM from receiving irrelevant documents just because nothing better matched.

4. Step 4 – Generate the answer: You pass the context and the question to the LLM using the chat format with messages. The system prompt explicitly instructs the model to answer using only the provided context. This is what keeps the LLM grounded. Without this instruction, it will ignore your context and answer from its training data instead.

5. Step 5 – Return sources: You include the source metadata in the response so callers know which documents the answer came from. The Set deduplicates sources in case multiple chunks came from the same document.

How to Test the Query Pipeline

Deploy your Worker:

npx wrangler deploy

Send a question:

curl -X POST https://rag-tutorial-simple.<your-subdomain>.workers.dev/query \
  -H "Content-Type: application/json" \
  -d '{"question": "What is RAG?"}'

On Windows PowerShell:

Invoke-WebRequest `
  -Uri "https://rag-tutorial-simple.<your-subdomain>.workers.dev/query" `
  -Method POST `
  -ContentType "application/json" `
  -Body '{"question": "What is RAG?"}' `
  -UseBasicParsing

You should receive a response like this:

{
  "answer": "RAG stands for Retrieval Augmented Generation. It's a method that enhances generation by retrieving relevant context from a knowledge base and adding it to the prompt before generating an answer.",
  "sources": ["ai-concepts"]
}

The answer came from your knowledge base, not from the LLM's training data. That's the entire point of RAG: grounded, verifiable answers with traceable sources.

How to Add Error Handling and Security

A tutorial that only shows the happy path is not production-ready. In this section, you'll add error handling to every step of the query pipeline and protect the /load endpoint from unauthorized access.

How to Secure the Load Endpoint

The /load endpoint generates embeddings and writes to your Vectorize index. Without protection, anyone who discovers your Worker URL can trigger it repeatedly, consuming your Workers AI quota and overwriting your data.

The LOAD_SECRET binding you added to Env and the wrangler secret put command you ran earlier handle this. The check at the top of handleLoad rejects any request that doesn't include the correct secret header:

const authHeader = request.headers.get("X-Load-Secret");
if (authHeader !== env.LOAD_SECRET) {
  return Response.json({ error: "Unauthorized" }, { status: 401 });
}

A request without the header returns {"error":"Unauthorized"} with a 401 status. The secret itself is stored as an encrypted environment variable in your Worker. It never appears in your code or wrangler.toml.

To trigger the load endpoint, you must include the secret in the request header:

curl -X POST https://rag-tutorial-simple.<your-subdomain>.workers.dev/load \
  -H "X-Load-Secret: your-secret-value"

How to Handle Query Errors

Replace your handleQuery function with this hardened version:

async function handleQuery(request: Request, env: Env): Promise<Response> {
  // Guard against malformed request body
  let body: { question: string };
  try {
    body = await request.json() as { question: string };
  } catch {
    return Response.json({ error: "Invalid JSON in request body" }, { status: 400 });
  }

  if (!body.question || typeof body.question !== "string" || body.question.trim() === "") {
    return Response.json({ error: "question must be a non-empty string" }, { status: 400 });
  }

  // Sanitize: trim whitespace and cap length
  const question = body.question.trim().slice(0, 500);

  // Step 1: Embed the question
  let embeddingResponse: { data: number[][] };
  try {
    embeddingResponse = await env.AI.run("@cf/baai/bge-base-en-v1.5", {
      text: [question],
    }) as { data: number[][] };
  } catch (err) {
    console.error("Embedding generation failed:", err);
    return Response.json({ error: "Failed to process your question" }, { status: 503 });
  }

  // Step 2: Search Vectorize
  let searchResults: Awaited<ReturnType<typeof env.VECTORIZE.query>>;
  try {
    searchResults = await env.VECTORIZE.query(
      embeddingResponse.data[0],
      { topK: 3, returnMetadata: "all" }
    );
  } catch (err) {
    console.error("Vectorize query failed:", err);
    return Response.json({ error: "Failed to search knowledge base" }, { status: 503 });
  }

  // Step 3: Build context
  const context = searchResults.matches
    .filter((match) => match.score > 0.5)
    .map((match) => match.metadata?.text as string)
    .filter(Boolean)
    .join("\n\n");

  if (!context) {
    return Response.json({
      answer: "I could not find relevant information to answer that question. Try rephrasing or asking something else.",
      sources: [],
    });
  }

  // Step 4: Generate answer
  let aiResponse: { response: string };
  try {
    aiResponse = await env.AI.run("@cf/meta/llama-3.3-70b-instruct-fp8-fast", {
      messages: [
        {
          role: "system",
          content: "You are a helpful assistant. Answer the question using only the context provided. If the context does not contain enough information, say so.",
        },
        {
          role: "user",
          content: `Context:\n\({context}\n\nQuestion: \){question}`,
        },
      ],
      max_tokens: 256,
    }) as { response: string };
  } catch (err) {
    console.error("LLM generation failed:", err);
    return Response.json({ error: "Failed to generate an answer" }, { status: 503 });
  }

  // Step 5: Return answer with sources
  const sources = searchResults.matches
    .filter((match) => match.score > 0.5)
    .map((match) => match.metadata?.source as string)
    .filter(Boolean);

  return Response.json({
    answer: aiResponse.response,
    sources: [...new Set(sources)],
  });
}

What each error handling decision means:

• try/catch around request.json(): request.json() throws if the body is not valid JSON. Without this catch, a malformed request crashes your Worker with an unhandled 500 error. With it, the caller gets a clear 400 explaining what went wrong.

• Input validation before processing: You check that question exists, is a string, and is not empty before calling any external service. This prevents wasted AI calls on invalid input.

• .slice(0, 500) on the question: This caps the input length before it reaches the embedding model. Without it, a malicious caller could send a very long string designed to inflate your AI usage or hit Workers CPU limits.

• 503 for AI and Vectorize failures: HTTP 503 means "service temporarily unavailable." It signals to callers that the error is on the server side and the request can be retried.

• .filter(Boolean) on context: After mapping match.metadata?.text, some results may be undefined if metadata was stored without a text field. This filters them out before joining, preventing "undefined" from appearing in the context string you send to the LLM.

How to Test Error Handling

Deploy your updated Worker:

npx wrangler deploy

Test each error case:

# Missing secret on load endpoint — should return 401
curl -X POST https://rag-tutorial-simple.<your-subdomain>.workers.dev/load

# Invalid JSON — should return 400
curl -X POST https://rag-tutorial-simple.<your-subdomain>.workers.dev/query \
  -H "Content-Type: application/json" \
  -d 'not json'

# Empty question — should return 400
curl -X POST https://rag-tutorial-simple.<your-subdomain>.workers.dev/query \
  -H "Content-Type: application/json" \
  -d '{"question": ""}'

Performance and Cost Analysis

This section uses real production data from my vectorize-mcp-worker deployment. It uses the same architecture you just built, measured from Port Harcourt, Nigeria to Cloudflare's edge.

Real Performance Numbers

Here is what the pipeline actually costs in time on every request:

This covers embedding generation and vector search only – the retrieval layer. LLM generation adds 500-1500ms on top, which is why end-to-end response time typically runs 600-1600ms.

The embedding step and vector search dominate. Everything else is negligible. For context, a comparable setup using OpenAI embeddings and Pinecone would add two external API roundtrips on top of this, easily pushing total latency past 1 second.

These numbers come from a single-region measurement. Your actual latency will vary based on your location and Cloudflare's load at the time of the request. The architectural point holds regardless: co-locating everything on the edge eliminates inter-service network hops, which is where most latency in traditional RAG stacks comes from.

Real Cost Breakdown

For 10,000 searches per day (300,000 per month) with 10,000 stored vectors:

This stack:

Traditional alternatives for the same volume:

That is an 85-95% cost reduction depending on which alternative you compare against. For a bootstrapped startup adding semantic search, that difference is $1,500-2,000 per year.

Why the Cost Difference Is So Large

Traditional RAG stacks have three cost problems that compound each other.

The first is idle compute. A dedicated server or container running your embedding service costs money even when no searches are happening. Cloudflare Workers charge only for actual execution time.

The second is inter-service data transfer. Every time your application calls an external service for an embedding, then calls a separate service for a search, you're paying for two external API calls with metered pricing. In this stack, both operations happen inside Cloudflare's network at no additional transfer cost.

The third is minimum plan pricing. Pinecone's Standard plan costs \(50/month as a floor, regardless of how little you use it. Cloudflare's pricing scales from the \)5/month Workers Paid plan base.

When the Included Allocation Is Enough

For smaller usage levels, you may not pay beyond the $5/month Workers Paid base price:

• Workers: 10 million requests per month included

• Workers AI: generous daily neuron allocation included

• Vectorize: available on both Free and Paid plans, with a free allocation included

A side project, internal tool, or small business with under 3,000 searches per day will likely stay within the included allocations entirely.

The Trade-off to Know About

This cost advantage comes with one operational constraint worth understanding before you build: Vectorize does not work in local development mode.

When you run wrangler dev, your Worker runs locally but Vectorize calls fail. You have to deploy to Cloudflare to test your vector search. For most development workflows this means testing your query logic locally with mocked responses, then deploying to a staging environment for full integration tests.

This is a real friction point. It's the honest trade-off for having a managed vector database with no infrastructure to operate.

Conclusion

In this tutorial, you have built and deployed a production-ready RAG system on Cloudflare's edge network. Let's look at what you actually built and what it costs to run.

What You Built

Your completed system has three endpoints:

• GET /: health check confirming the Worker is running

• POST /load: loads your knowledge base into Vectorize, protected by a secret header

• POST /query: accepts a question, retrieves relevant context, and returns a grounded answer with sources

The full query pipeline runs in four steps on every request:

1. The question is converted to a 768-dimensional embedding using @cf/baai/bge-base-en-v1.5

2. Vectorize finds the three most semantically similar documents

3. Documents above the 0.5 similarity threshold are assembled into context

4. Llama 3.3 generates an answer using only that context

Everything runs on Cloudflare's infrastructure. No external API keys. No separate vector database subscription. No servers to manage.

What to Build Next

This tutorial covered the core RAG pattern. Here are four directions to take it further.

Add more documents

The knowledge base in this tutorial has 8 documents. A real system might have thousands. The loading pattern is identical: add documents to knowledge-base.ts, hit /load with your secret, and Vectorize handles the rest.

For very large knowledge bases, update handleLoad to batch documents in groups of 20-50 rather than upserting one at a time.

Improve chunking

Each document in this tutorial is a single short paragraph. Real-world documents like PDFs, articles, documentation pages need to be split into chunks before embedding. Chunk at natural boundaries like paragraphs and sentences, aim for 200-400 tokens per chunk, and include 50-token overlaps between chunks to preserve context across boundaries.

Add conversation history

The current system treats every query as independent. To support follow-up questions, store previous messages in a Cloudflare KV namespace and include the last 2-3 exchanges in the LLM messages array alongside the retrieved context.

Stream the response

For long answers, users stare at a blank screen until generation completes. Cloudflare Workers support streaming responses via TransformStream. Switching to streaming means the first tokens appear in under 100ms while the rest generates.

Consider dimensions vs reranking trade-offs

This tutorial uses bge-base-en-v1.5 at 768 dimensions. My production system uses bge-small-en-v1.5 at 384 dimensions. Testing showed upgrading from 384 to 768 dims only improved accuracy by about 2%, but doubled cost and latency.

Adding a reranker (@cf/baai/bge-reranker-base) gave a larger accuracy improvement than the dimension upgrade for a fraction of the cost. The exact improvement will vary by domain and query distribution — test both on your actual data before deciding. If you're optimizing for production, add a reranker before you increase dimensions.

The Complete Project

Clone and deploy in five commands:

git clone https://github.com/dannwaneri/rag-tutorial-simple
cd rag-tutorial-simple
npm install
npx wrangler vectorize create rag-tutorial-index --dimensions=768 --metric=cosine
npx wrangler secret put LOAD_SECRET
npx wrangler deploy

Then load your knowledge base:

curl -X POST https://<your-worker>.workers.dev/load \
  -H "X-Load-Secret: your-secret"

If you found this useful, the production system this tutorial is based on is open source at github.com/dannwaneri/vectorize-mcp-worker. It extends this foundation with hybrid search combining vector and BM25, multimodal support for searching images with AI vision, a reranker for more accurate results, and a live dashboard. It runs on the same Cloudflare stack you just built – Workers, Vectorize, Workers AI – plus D1 for document storage.

One difference you'll notice: the production system uses bge-small-en-v1.5 at 384 dimensions rather than the 768 dimensions in this tutorial. That is an intentional trade-off: the reranker adds more accuracy than the extra dimensions at lower cost. The jump from what you built today to that system is smaller than it looks.

As projects grew in complexity and teams worked in parallel across different stacks, it became clear that monolithic approaches couldn’t keep up. I needed practical tools that allowed easy cross-app interaction, independent deployability, better team autonomy, framework-agnosticism, and more. Some solutions worked elegantly in theory but struggled in real-world conditions. Others made things messier and more painful than helpful.

After diving deep into different paradigms—from iframes to Web Components, single-spa, Module Federation, Piral, Luigi, and hybrid setups—I even distilled my proven experience into a full-fledged online course on Udemy.

And today, in this comprehensive hands-on tutorial, I want to share my expertise and tell you more about micro-frontend architecture—method by method—with code, tradeoffs, visuals, and real-world insights.

Table of Contents

• What are Micro Frontends For?

• Method #1: Iframes & Cross-Window Messaging

• Method #2: Web Components (Custom Elements + Shadow DOM)

• Method #3: Single-SPA — The Meta-Framework Approach

• Method #4: Module Federation - Sharing Code at Runtime

• Other Tools & Ecosystem Additions

• Final Thoughts

What are Micro Frontends For?

In traditional frontend development, we often build single, monolithic apps—one codebase, one repo, one deployment pipeline, one team. It works great for small to medium projects, sometimes even for larger ones.

But challenges arise when:

• Your frontend codebase expands beyond 50+ components.

• Multiple development teams need autonomy over different parts and tech stacks.

• Different sections require varying deployment frequencies (weekly or monthly).

• You need to integrate diverse frameworks, like combining React features with an Angular-based CMS.

This is where micro frontends step in.

Micro frontends extend the principles of microservices to the frontend world. Instead of one big frontend app, you build independent frontend modules, each owned by a team, using its own tech stack, deployed separately, and integrated at runtime.

Think of it like Lego blocks:

• Each block is similar to a self-contained micro frontend.

• They plug into a shared layout or shell.

• Each can evolve, update, or be replaced without affecting the others.

For example, imagine that you’re building a modern e-commerce site, and here’s what your business side expects from you:

Each team wants autonomy, and with micro frontends, each of these sections becomes a separate app, loaded dynamically into a shell at runtime.

Why It’s Getting Popular?

Here are a few things everyone considers:

1. Independent deployments – A little or no effort to coordinate every release.

2. Team autonomy – Teams choose their own stack and tools on the project.

3. Incremental upgrades – Migrate legacy apps piece by piece incrementally without the need to rewrite the whole app at once.

4. Technical agnosticism – Vue, React, Angular? Doesn’t matter. They can all work together seamlessly at the same time in a single app.

5. Better scalability – Parallelize work across teams to enable efficiency of delivery and scale at ease.

Now let’s discover how we can bring this idea to life in our projects.

Nowadays, there are different ways to achieve that, but not all solutions are equal. The implementation method you choose will drastically affect:

• Developer experience

• Bundle sizes and performance

• SEO and accessibility

• Runtime stability

• Interoperability across stacks

So let’s begin by exploring the oldest, but still surprisingly viable method.

Method #1: Iframes & Cross-Window Messaging

You may ask, “Aren’t iframes bad?” They’re often misunderstood. While yes, iframes can feel clunky and isolated, they’re also the most secure and decoupled way to host micro frontends—especially when you don’t trust the team on the other side.

What Is an IFRAME?

An iframe (inline frame) is an HTML element that allows you to embed another HTML page within your current webpage. The whole communication between apps is strictly based on events and delivered by means of the Post Message API.

If you need to send data to another app, you simply call the postMessage() method on that element. On the other side, to receive a message, you just have to subscribe to the message event. That’s it.

Real-World Example

Let’s see a simple example of two apps communicating with each other using iframes on two apps:

• The Main Web App

• A Search App.

Every iframe must be hosted somewhere to serve static content from it. It can be AWS Amplify, Digital Ocean, Heroku, GitHub Pages, or alike.

To help you out here, here’s an official GitHub guideline explaining how to host a website on their platform.

Let’s say you deployed a Search App on Github Pages and you were given this URL to host your app: https://example.github.io. Now let’s write some content for it.

Assuming that you want to post messages from the Search App to the Main Web App, and to subscribe to the incoming messages from it there. You can do it in this way:

console.log('Initializing Search App...');

// Subscribe to messages from outside the iframe (like Main Web App)
window.addEventListener('message', (event) => {
  if (event.data?.type === 'init') {
    console.log('Main Web App passed userId:', event.data.userId);
  }
});

// Simulate sending Search results back to Main Web App
window.parent.postMessage({
  type: 'searchResult',
  payload: ['Item A', 'Item B']
}, '*');

Here, you initialize the search app and set up two-way communication with a parent application (such as a main web app) using the Post Message API. You listen for incoming messages using the built-in message event. Once received, that message becomes available in the event.data object. Finally, you simulate sending data back to the parent by posting a searchResult message containing a list of items. This setup enables isolated iframe-based apps to communicate safely with the main shell application.

Then, in the DOM of the main web app, you need to include the iframe that will render the search app, specifying the URL to the hosted search app in this way:

<iframe
  id="search-mfe"
  src="https://example.github.io"
  style="width: 100%; height: 200px; border: none;"
></iframe>

Styles were added here to ensure that the iframe displays seamlessly within the layout for a cleaner UI integration.

And now you can pass some content from the main web app down to the search app and get some messages from it. You can accomplish it in the main web app’s JavaScript code in this way:

console.log('Initializing Main Web App...');

const iframe = document.getElementById('search-mfe');
iframe.onload = () => {
  // Send message to child iframe (inputs)
  iframe.contentWindow.postMessage({ type: 'init', userId: 42 }, '*');
};

window.addEventListener('message', (event) => {
  // Receive data from the Search App (outputs)
  if (event.data?.type === 'searchResult') {
    console.log('Received result from Search App: ', event.data.payload);
  }
});

As you see, when the iframe loads, the init event is sent to the search app (the type can be anything you want, just ensure it matches the one that another app expects from you). And then, in the message event handler as before, you can receive the incoming messages from the search app, and do something with them.

Here are a few pros and cons to consider, along with popular use cases:

✅ Pros:

• Strong sandboxing: No shared memory, no shared styles.

• Zero dependency clashes: One iframe is equivalent to one environment.

• Perfect for legacy: Easy to wrap old apps in an iframe.

• Practical for micro-apps in PHP, Java, Razor (ASP.NET)

❌ Cons:

• Slow rendering

• Difficult shared navigation

• Inconsistent/complicated styling

• Complex communication

• Must be hosted somewhere

👨🏻‍💻 Popular Use Cases

• Embedding legacy dashboards (for example, old AngularJS or Java apps)

• Secure cross-domain apps (for example, payments, 3rd party analytics)

• Highly untrusted integrations

• Embedded Ads

But if you want a more fluid UX, shared components, and a smoother dev experience, you’ll want something better. That brings us to Web Components.

Method #2: Web Components (Custom Elements + Shadow DOM)

“What if you could ship a self-contained natively understood widget that works in any framework — React, Vue, Angular, or plain HTML?”

That’s exactly what Web Components make possible. They’re natively built into the browser as an API, you don’t need a framework or extra dependency. They allow you to create reusable, scalable, encapsulated UI elements that work just like native HTML tags.

Moreover, you can easily use them as wrappers around any elements from other UI frameworks (React, Angular, Svelte, etc) and use your framework-based components as regular native DOM elements in any web application.

They are, in many ways, the ideal foundation for micro frontends.

A web component is made of:

• Custom Element - defines your own HTML tag (<user-profile>) and behavior

• Shadow DOM – provides scoped, encapsulated styles and DOM structure

• HTML Template – brings reusable HTML blocks/fragments

• Slots – acts as placeholder areas for host content (used in content projection)

In web components, you have to sync the data (input/output) via:

• Attributes (inputs):

  • In Javascript: element.setAttribute(), element.getAttribute(), and so on.

  • In HTML: <element attr1=”value1” attr2=”value2”></element>

• Properties (inputs) – element.someProp = value (only Javascript)

• Custom Events (outputs) - new CustomEvent('name', data)

First, let me show you a basic implementation of a web component, and then you’ll learn how to leverage it for micro-frontends.

Assuming that you’re building a reusable product-tile component that must:

• Accept one input parameter – “title”

• Send an output event "add-to-cart" with this “title” to the outside world, when the component is mounted to the DOM.

Here’s how this web component could look:

// product-tile.js
class ProductTile extends HTMLElement {
  // Specify which attributes (inputs) to observe for changes
  static get observedAttributes() { return ['title']; }

  constructor() {
      super(); // Call base HTMLElement constructor (obligatory)
      // Create a Shadow DOM for style and DOM encapsulation
      const shadow = this.attachShadow({ mode: 'open' });
      // Populate Shadow DOM with a DIV container where React will render the player
      shadow.innerHTML = `<div id="title"></div>`;
  }

  // Built-in Lifecycle Reaction.
  // Called when the custom element ProductTile is added to the DOM
  connectedCallback() {
      // When added to the DOM, read and render the title attribute
      const title = this.getAttribute('title') ?? 'Unnamed Product';
      this.updateTitle(title);

      // Dispatch a custom event with the current title
      const event = new CustomEvent('add-to-cart', {
          detail: { title },
          bubbles: true,
          composed: true,
      });

      this.dispatchEvent(event);
  }

  // Built-in Lifecycle Reaction.
  // Called whenever observed attributes change.
  // In our case it's "title" only
  attributeChangedCallback(name, oldValue, newValue) {
      if (name === 'title' && oldValue !== newValue) {
          this.updateTitle(newValue);
      }
  }

  // Internal method to safely update the title content
  updateTitle(title) {
      const titleElem = this.shadowRoot.querySelector('#title');
      titleElem.textContent = title;
  }
}

customElements.define('product-tile', ProductTile);

Now, let me explain what’s happening here:

• First, you create a custom element class that extends from HTMLElement or its children. This gives you access to web component lifecycle hooks and DOM integration capabilities.

• If you want to react to changes in input parameters (attributes), you have to define a static observedAttributes() getter that returns a list of attribute names to watch. In our case, we observe “title”.

• Then, in the constructor:

  • Call super() to properly inherit from HTMLElement.

  • Create a shadow DOM using attachShadow({ mode: 'open' }). This encapsulates your component’s internal DOM and styles. You can even use a closed mode here to add a higher level of isolation to the shadow DOM.

  • Then, populate the shadow DOM with minimal inner HTML—in this case, a <div> element that will later display the product title.

• When the component is added to the DOM, the built-in connectedCallback() lifecycle reaction runs:

  • It reads the current value of the "title" attribute.

  • Updates the UI with an initial value in the "title" attribute.

  • Then it dispatches a custom event named "add-to-cart", passing the "title" as detail down to it. The events are bubbles: true and composed: true, so that parent elements or host apps outside the shadow DOM can subscribe to it and catch it.

• When the title attribute changes at runtime, another built-in lifecycle reaction named attributeChangedCallback() runs automatically:

  • It checks the new value and updates the "title" display accordingly.

  • This enables reactive behavior in the component—similar to input bindings in UI frameworks.

• Finally, you register the component globally using customElements.define() method (it’s available in the global window object), giving it:

  • A tag name of <product-tile> that can be used anywhere in HTML.

  • A reference to the custom element you previously created to associate one with another.

Ultimately, here’s how you can use this component in your apps, which will work in vanilla JS, React, Angular, Svelte, Vue, whatever UI framework you choose:

<product-tile title="Coffee Mug"></product-tile>

And then you can listen to the "add-to-cart" event from inside ProductTile component like so:

const elem = document.querySelector('product-tile');
elem.addEventListener('add-to-cart', e => {
  console.log('Add to cart!', e.detail);
});

As you see, no ReactDOM.render, no NgModule, no extra glue. Everything is entirely native, pure JavaScript code that browsers understand.

And now, due to the Shadow DOM and other Web Components’ features, you can easily wrap and embed any web app written in a different framework into the Shadow Tree that will isolate your app entirely and won’t allow its layout or styles to leak out.

Alternatively, if you decide to publish it as a separate npm package (for example, @webcomp/product-tile), you can even dynamically import and mount the Web Component like so:

import('@webcomp/product-tile').then(() => {
  // Now <product-tile> is defined — you can create and use it
  const elem = document.createElement('product-tile');
  elem.setAttribute('title', 'Wireless Mouse');
  document.body.appendChild(elem);
});

Or load from CDN or any hosting provider:

<script type="module" src="https://example.github.io/product-tile.js"></script>

It’s simple, clean, and independent.

But you’re not here just for that, right? :) Now, let’s learn the real power of Web Components in a micro-frontends world!

Micro-Frontends with Web Components

Imagine that you’ve built a Video Player in React—or perhaps want to reuse one from another team. Now the question is: How can you make this React-based player usable in any other frontend application, regardless of its underlying framework, using Web Components?

Let’s figure it out!

Let’s say, this video player:

• Accepts src and controls as inputs

• Emits events: play and pause as outputs

• Can be used in any app via <magic-player> in this way:

    <magic-player
      src="https://cdn.example.com/video.mp4"
      controls="true"
    ></magic-player>
  

Now let’s get to implementation!

🔹 Step #1: Include your React player in the project

Here, you can play around with any React component of your choice, to be honest, or you can just use a simple React Video Player like the one below:

// ReactVideoPlayer.jsx

import React from 'react';

export function ReactVideoPlayer({ src, controls, onPlay, onPause }) {
  return (
      // HTML5 video element with full width and controls enabled
    <video
      width="100%"
      controls={controls}  {/* Enable / Disable controls */}
      onPlay={onPlay}      {/* Callback for play event */}
      onPause={onPause}    {/* Callback for pause event */}
    >
      <source src={src} type="video/mp4" />
      Your browser does not support the video tag.
    </video>
  );
}

🔹 Step #2: Create the Web Component Wrapper

Now, you need to create a Web Component wrapper around this React player app by mounting it into the shadow DOM of a custom element in this way:

// magic-player.element.js

// Define a new custom element class
class MagicPlayerElement extends HTMLElement {
  constructor() {
    super(); // Call base HTMLElement constructor (obligatory)

    // Create a Shadow DOM for style and DOM encapsulation
    const shadowRoot = this.attachShadow({ mode: 'open' });
    // Populate Shadow DOM with a DIV container where React will render the player
    shadowRoot.innerHTML = `
        <div id="react-video-player"></div>
    `;
  }
}

customElements.define('magic-player', MagicPlayerElement);

Then you need to add inputs and outputs like so:

// magic-player.element.js

// Define a new custom element class
class MagicPlayerElement extends HTMLElement {
  // Specify which attributes (inputs) to observe for changes
  static get observedAttributes() { return ['src', 'controls']; }

  constructor() {
    super(); // Call base HTMLElement constructor (obligatory)

    // Create a Shadow DOM for style and DOM encapsulation
    const shadowRoot = this.attachShadow({ mode: 'open' });
    // Populate Shadow DOM with a DIV container where React will render the player
    shadowRoot.innerHTML = `
        <div id="react-video-player"></div>
    `;
  }

  // Helper-like method to dispatch native-like events (our outputs)
  // In our case, it will be triggered for "onPlay" and "onPause" events
  dispatch(eventName, detail = {}) {
      const event = new CustomEvent(eventName, {
      detail,            // Pass custom data ("onPlay" or "onPause")
      bubbles: true,     // Allow event to bubble up
      composed: true     // Allow it to cross the Shadow DOM boundary
    });
    this.dispatchEvent(event);
  }
}

customElements.define('magic-player', MagicPlayerElement);

And lastly, add two built-in lifecycle reactions to render a React video player app when the page loads and every time the inputs change:

// magic-player.element.jsx

// Define a new custom element class
class MagicPlayerElement extends HTMLElement {
  // Specify which attributes (inputs) to observe for changes
  static get observedAttributes() { return ['src', 'controls']; }

  constructor() {
    super(); // Call base HTMLElement constructor (obligatory)

    // Create a Shadow DOM for style and DOM encapsulation
    const shadow = this.attachShadow({ mode: 'open' });
    // Populate Shadow DOM with a DIV container where React will render the player
    shadow.innerHTML = `
        <div id="react-video-player"></div>
    `;
  }

  // Helper-like method to dispatch native-like events (our outputs)
  // In our case, it will be triggered for "onPlay" and "onPause" events
  dispatch(eventName, detail = {}) {
      const event = new CustomEvent(eventName, {
      detail,            // Pass custom data ("onPlay" or "onPause")
      bubbles: true,     // Allow event to bubble up
      composed: true     // Allow it to cross the Shadow DOM boundary
    });
    this.dispatchEvent(event);
  }

  // Built-in Lifecycle Reaction.
  // Called when the custom element <magic-player> is added to the DOM
  connectedCallback() {
    this.render();
  }

  // Built-in Lifecycle Reaction.
  // Called whenever observed attributes change.
  // In our case it's "src" and "controls"
  attributeChangedCallback() {
    this.render();
  }

  // Render the React player inside the container
  render() {
    const src = this.getAttribute('src');
    const controls = this.getAttribute('controls') === 'true';
    const mount = this.shadowRoot.querySelector('#react-video-player');

    ReactDOM.createRoot(mount).render(
      <ReactVideoPlayer
        src={src}
        controls={controls}
        onPlay={() => this.dispatch('play')}
        onPause={() => this.dispatch('pause')}
      />
    );
  }
}

customElements.define('magic-player', MagicPlayerElement);

🔹 Step #3: Connect your React-Player to any UI framework:

Then, in the main web app (whatever UI framework you’re using there). We put our newly created React video player wrapper in any place in the DOM, passing down initial attributes (inputs) to it:

<!-- Use your new React-based player anywhere! -->
<magic-player
  src="https://cdn.example.com/movie.mp4"
  controls="true"
></magic-player>

And then you can easily subscribe to the custom events (outputs) from inside the React app:

// Listen to native-style events from the custom element
const magicPlayer = document.querySelector('magic-player');
magicPlayer.addEventListener('play', () => {
  console.log('Video has started playing!');
});

magicPlayer.addEventListener('pause', () => {
  console.log('Video has been paused.');
});

That’s it! Now, try to accomplish the same with a different UI framework!

✅ Pros

• Framework-agnostic: Works in React, Angular, Vue, Svelte, or even plain HTML — no rewrites needed

• Natively supported by browsers: No need for external libraries or frameworks — just HTML, JS, and CSS.

• No extra configuration or hosting needed as in iframes. But still, components can be published to npm/CDNs and reused across multiple apps.

• Intuitive & easy communication: Expose native DOM attributes as inputs and native custom events as outputs.

• SSR-friendly with hydration: It supports serialization, declarative shadow DOM, and can be server-rendered and hydrated, especially using modern tools.

• Supports Accessibility (ARIA attributes and roles).

❌ Cons

• Integration Difficulties: If you want to bridge two apps in different technical stacks, you need to properly manage their communication in a custom element wrapper and its shadow DOM.

• Limited Support for old Browsers: If you need compatibility with legacy browsers like Internet Explorer 10, Web Components need a polyfill. But here’s a popular repository with all polyfills for Web Components: https://github.com/webcomponents/polyfills

• Global State Isolation: There’s no built-in way to share state across components. You’ll need to implement your own global bus or event bridge using CustomEvents or alike.

👨🏻‍💻 Popular Use Cases

• Reusable Design systems & UI libraries

• Micro frontends inside framework apps

• Legacy integration to modern stack and vice versa

• Cross-team component delivery

• CDN-based plug-and-play UIs

The Web Components API has many more possibilities and power. So, if you want, you can go deeper and advance your knowledge by passing any available free course on freeCodeCamp or passing the one I’ve built myself around this technique on Udemy.

Now let’s move on!

Method #3: Single-SPA — The Meta-Framework Approach

“What if instead of embedding micro frontends as Web Components or iframes, we had a system that orchestrated multiple SPAs together in one layout?”

That’s what single-spa is all about. It’s not a rendering library, it’s a runtime JavaScript router and orchestrator for micro frontends.

Source: https://single-spa.js.org

What Is single-spa?

single-spa (Single Page Application) lets you build and run multiple independent SPAs (React, Vue, Angular, and so on) inside one webpage. Each SPA is responsible for part of the UI and is loaded dynamically depending on the current route.

In short, it’s a framework that:

• Loads your micro frontends when needed

• Mounts/unmounts them cleanly

• Coordinates routing and lifecycles

• Supports different frameworks in the same app.

Real-Life Example

Let’s say you have this route breakdown:

Each one is a fully independent SPA, and single-spa loads them as needed.

🔹 Step #1: single-spa installation

First, you need to install the single-spa as a dependency for your project:

# Create a new project (if it's not yet)
npm init

# Install Single SPA
npm install single-spa systemjs

Notice that we also installed the systemjs package. This package is responsible for the dynamic runtime module loading that makes Single-SPA work seamlessly. It uses SystemJS as a module loader to allow micro frontends to be:

1. Loaded at runtime

2. Independently deployed

3. Framework-agnostic

4. Lazy-loaded only when needed

Now you need to implement each micro-app. For instance, let’s see how the @shop/products app written in React could be managed.

🔹 Step #2: Project Structure

The project structure for each micro app can look like this:

shop/products/
├── src/
│   ├── root.component.jsx
│   └── index.single-spa.js
├── public/
│   └── index.html
├── package.json
└── webpack.config.js

🔹 Step #3: Root Micro App Component

The root.component.jsx file represents the root of the React app that will be mounted to the main DOM using single-spa. Here’s a simple example:

// src/root.component.jsx
import React from 'react';

export default function Root() {
  return (
    <div style={{ padding: '1rem', border: '1px solid #ccc' }}>
      <h2>🛍 Product Micro App</h2>
      <p>This is a micro frontend powered by React + Single-SPA!</p>
    </div>
  );
}

🔹 Step #4: Set Up Lifecycle Hooks

Also, each Micro App in single-spa requires an entry point with at least three core functions/lifecycle hooks. For that purpose, you will need a separate file, which you can name as index.single-spa.js and it will provide the implementation of those hooks, like:

• bootstrap() - Called when the micro app is launched by the main app (Shell) before mounting to the DOM

• mount() - Called when the app is attached to the host in the DOM

• unmount() - Called when the app is removed/detached from the DOM

And here’s an example of what they could look like:

// src/index.single-spa.js

import React from 'react';
import ReactDOM from 'react-dom/client';
import Root from './root.component.jsx';

// Hold the React root instance for reuse
let root = null;

// Called once when the micro frontend is first initialized
export function bootstrap() {
  return Promise.resolve();
}

// Called every time the route matches and the app should appear
export function mount(props) {
  return Promise.resolve().then(() => {
    const container = document.getElementById('product-container') || createContainer();
    root = ReactDOM.createRoot(container);
    root.render(<Root />);
  });
}

// Called when the route no longer matches (cleanup)
export function unmount() {
  return Promise.resolve().then(() => {
    if (root) {
      root.unmount();
    }
  });
}

// Create a container div if it doesn't exist
function createContainer() {
  const div = document.createElement('div');
  div.id = 'product-container';
  document.body.appendChild(div);
  return div;
}

As you see, you have to resolve a Promise in all lifecycle hooks and ensure the React app is mounted and unmounted properly based on the React best practices.

🔹 Step #5: Configuring Webpack for SystemJS

Also, each micro-app in single-spa needs a separate configuration. For that, you will include a webpack.config.js file, specifying how to build the app (output), where to host it (publicPath), and so on.

Since single-spa uses the SystemJS package, the libraryTarget will be system for all micro apps.

// webpack.config.js
module.exports = {
  externals: {
    react: 'React',
    'react-dom': 'ReactDOM',
  },
  output: {
    filename: 'products.js',
    libraryTarget: 'system', // SystemJS-compatible format
    publicPath: 'http://localhost:8500/', // Host location of this micro app
  },
};

This app will be hosted on the localhost:8500. For production, you will have to use any suitable hosting provider (like the ones described in the iframes section).

🔹 Step #6: Registering the Micro App in Root-Config

Next, it’s time to register a new micro-app in the Singla-SPA root config. Here’s how you can do it:

Create a root-config.js file in the root of the project and fill it with this content:

// root-config.js (host shell)
import { registerApplication, start } from 'single-spa';

registerApplication({
  name: '@shop/products',
  app: () => System.import('@shop/products'),
  activeWhen: ['/products'],
});

start(); // Initializes routing and micro app lifecycles

First, you have to register the application, and then you start it to enable routing and the micro app lifecycle. The registration for other micro apps will look the same.

Note: System.import() is part of SystemJS, used by default in single-spa for loading remote apps.

Also, single-spa comes with so-called "Parcels" – a lower-level construct in comparison to applications. They’re essentially self-contained pieces of UI that you can dynamically mount anywhere. Think of them like “mini microfrontends” or reusable widgets that don’t control routing:

// Example
mountParcel(SomeParcelComponent, { domElement: document.getElementById('micro-app') });

You’d use them when:

• You don’t want the parcel to own a route.

• You need to inject a micro frontend dynamically inside another one.

• You want encapsulated logic (like a widget) embedded within a larger app.

In all other cases, prefer the usage of a registerApplication(...) function.

🔹 Step #7: Adding Micro App to SystemJS Import Map

The last step is to register the micro app in SystemJS. For that, in your root index.html file, you need to add the following two scripts:

<!-- public/index.html -->

<!DOCTYPE html>
<html lang="en">
<head> <title>Micro Frontend Shell</title> </head>
<body>
  <nav>
    <a href="/products">Products</a> |
    <a href="/checkout">Checkout</a>
  </nav>

  <!-- Import maps handled by bundler or injected at runtime -->
  <script type="systemjs-importmap">
    {
      "imports": {
        "@shop/root-config": "http://localhost:9000/root-config.js",
        "@shop/products": "http://localhost:8500/products.js",
        // other micro apps
      }
    }
  </script>

  <!-- Start the root-config application -->
  <script>
    System.import('@shop/root-config');
  </script>
</body>
</html>

First, you have to add a script with an import map declaration. As you see, it represents a JSON where:

• Each key is the micro app name and

• Each value is the URL where the main JS file (from the bundle) actually lives

Note that we’ve added the @shop/root-config here to the import map to tell SystemJS where to fetch the main JavaScript file for the main/shell app so it knows how to resolve and execute System.import('@shop/root-config') properly.

Secondly, you include another script to start the main / shell application. It executes the JS file you just mapped in the import map above. Treat it as the real “boot” of your shell app:

<script>
  System.import('@shop/root-config');
</script>

That’s it! Now go ahead and try doing the same with other micro-apps in Vue (Checkout App) and Angular (Account Dashboard).

Here’s a simple diagram illustrating this connection:

Now that you’ve registered and integrated your first micro app, you might be wondering if this approach right for you. Let’s quickly look at the benefits and limitations of using single-spa in production.

✅ Pros

• Built-in Routing & Lifecycles - No need to reinvent navigation or mounting logic

• Cross-framework support - React, Vue, Angular can all co-exist

• Fine-grained loading - Only load the active app (lazy and efficient)

• Flexible project structure - can be monorepo or polyrepo

• Good CLI tooling - create and link MFEs with create-single-spa & helpers

❌ Cons

• Complex learning curve - Lifecycle APIs and SystemJS can be intimidating

• Configurations can get verbose – Managing multiple registries, import maps, deployment URLs, and lifecycle wrappers across apps adds setup overhead

• Shared state is manual - You must implement custom global state solutions

• Hard to SSR - Designed for full client-side rendering

• More boilerplate - Each app needs wrappers for lifecycles, routing, and so on.

• Global styles leak - No default encapsulation like Shadow DOM

And a few popular use cases for it:

👨🏻‍💻 Popular Use Cases

You can use single-spa when:

• You want a central router managing all micro frontends

• Teams are using different frameworks

• You prefer full SPA experiences over isolated widgets

• You don’t mind some boilerplate for orchestration

• You’re okay with a purely client-side setup

Let’s move on!

Method #4: Module Federation - Sharing Code at Runtime

“What if your micro frontends could load each other’s components, modules, or libraries at runtime — without iframes, without import maps, and without repackaging?”

That’s exactly what Module Federation, introduced in Webpack 5, makes possible. It’s fairly new and it allows multiple, separately built and deployed applications to share modules in real-time, via the browser.

Source: https://module-federation.io/

With Module Federation, you can:

• Import components across independent builds

• Share React, Vue, or any dependency

• Version-control exposed modules

• Ship independently, yet consume each other

Module Federation is what makes micro frontends in a single cohesive layout truly feel like one app.

Now let’s see it in action!

Real-Life Example

Let’s assume that you have to build two self-contained apps:

• Main / Host app (shell) — loads components from others (let’s say it’s in React)

• Remote app (product-app) — exposes components written also in React to others

Module Federation allows you to export these components without publishing them to NPM or wrapping them as a Web Component. Instead, the host app will load the component directly at runtime from the compiled JavaScript bundle.

Here’s how the project structure could look:

Product App:

product-app/                ← Remote Micro Frontend
├── public/
│   └── index.html          ← Mount point for optional local test render
├── src/
│   ├── ProductTile.jsx     ← Component to expose
│   └── index.js            ← Optional: local entry point
├── webpack.config.js       ← Exposes Product App
├── package.json
└── .babelrc / .gitignore / etc

Note, that webpack.config.js must be at the root level, same as package.json, so Webpack can locate it automatically.

Main / Host App (shell):

host-app/                     
├── public/
│   └── index.html        ← Mount point
├── src/
│   ├── App.jsx           ← Mounts ProductTile from remote
│   └── bootstrap.js      ← App entry point
├── webpack.config.js     ← Loads remotes via Module Federation
└── package.json

You can keep them both in a monorepo or host them in entirely different repos.

🔹 Step #0: Initiate projects (Host + Product Apps)

If you know how to do it, you can set up two separate React applications yourself for the Host App and one for the Remote (Product App), or initialize them in this way:

npm init
npm install react react-dom

🔹 Step #1: Install Webpack 5 + dependencies (Host + Product Apps)

Before you do anything federation-related, both the host and remote apps must be set up with Webpack 5 and its plugins. Go ahead and run this in both projects:

npm install webpack webpack-cli webpack-dev-server html-webpack-plugin --save-dev

A few notes about these packages:

• webpack + webpack-cli — Core bundler and CLI

• webpack-dev-server — Local server for hot reload + module exposure

• html-webpack-plugin — Automatically injects your bundles into HTML

• Optional but common: You can add Babel, React preset, loaders, and so on, for JSX/TSX support later.

This setup gives you a foundation. From here, you can add module federation to connect apps together.

🔹 Step #2: Create the Remote App (Product App)

Let’s start with the remote app, the one exposing a React component to be consumed by others.

Here’s a simple ProductTile React component (of course, you can implement yours):

// product-app/src/ProductTile.jsx

import React from 'react';

export default function ProductTile({ title }) {
  return (
    <div style={{ border: '1px solid #aaa', padding: '1rem' }}>
      <h3>🛍 {title}</h3>
    </div>
  );
}

A ProductTile component supplies a prop – “title” – and renders it.

Now let’s expose this component to other apps, not just render it locally.

🔹 Step #3: Configure Webpack in the Remote App (Product App)

This will be done utilizing module federation, which you must enable in webpack.config.js file. Here’s how it can be done. At the very top of the file, you will need to import these packages:

// product-app/webpack.config.js

const HtmlWebpackPlugin = require('html-webpack-plugin');
const ModuleFederationPlugin = require('webpack').container.ModuleFederationPlugin;
const path = require('path');

• HtmlWebpackPlugin – Handles HTML generation and script injection.

• ModuleFederationPlugin – The core Webpack plugin that lets you expose and consume modules at runtime

Then, define the actual config in module.exports:

// product-app/webpack.config.js

const HtmlWebpackPlugin = require('html-webpack-plugin');
const ModuleFederationPlugin = require('webpack').container.ModuleFederationPlugin;
const path = require('path');

module.exports = {
  entry: './src/index.js',                         // Entry file to the product app
  mode: 'development',                             // Must be production if you go live
  devServer: {
    port: 3001                                     // Product app runs on this port
  },
  output: {
    publicPath: 'auto',                            // Required for dynamic federation
  },
  plugins: [
    new ModuleFederationPlugin({
      name: 'productApp',                         // Internal name of the remote app
      filename: 'remoteEntry.js',                 // Entry file others will load
      exposes: {
        './ProductTile': './src/ProductTile.jsx', // Expose this module
      },
      shared: {                                   // Shared packages if needed
        react: { singleton: true },
        'react-dom': { singleton: true },
      },
    }),
    new HtmlWebpackPlugin({
      template: './public/index.html',
    }),
  ],
};

Now it’s time to use the product app in the main/host app:

// host-app/src/App.jsx

import React, { Suspense } from 'react';

// Dynamically import ProductTile from the remote
const RemoteProductTile = React.lazy(() => import('productApp/ProductTile'));

export default function App() {
  return (
    <div style={{ padding: '2rem' }}>
      <h1>📦 Host App</h1>
      <Suspense fallback={<div>Loading product tile...</div>}>
        <RemoteProductTile title="Bluetooth Speaker" />
      </Suspense>
    </div>
  );
}

In React, you can use the React.lazy() function to dynamically import the federated module. It returns a promise that React renders as soon as it’s ready.

That’s it. There’s nothing related to the module federation in the bootstrap.js and index.html files, but regular setup, so you can put whatever you want there:

// host-app/src/bootstrap.js

import React from 'react';
import { createRoot } from 'react-dom/client';
import App from './App';

const root = createRoot(document.getElementById('root'));
root.render(<App />);

<!-- host-app/public/index.html -->

<!DOCTYPE html>
<html>
  <head>
    <title>Host App</title>
  </head>
  <body>
    <div id="root"></div>
  </body>
</html>

And lastly, you can launch the host app:

npx webpack serve

That’s it!

Here are a few advantages and limitations of Module Federation, along with popular use cases.

✅ Pros

• Runtime Integration – Import remote components after both apps are built

• Independent Deployment – Teams can ship apps on separate pipelines

• Code Sharing – Share common libraries (React, lodash) to reduce duplication

• No iframes or wrappers – Native component integration, not isolated like Web Components

• No import maps needed – Webpack handles all the resolution logic

• Works across frameworks – Can be used in React, Angular, Vue, even Web Components

❌ Cons

• Tied to Webpack – Federation is Webpack-specific (Vite/Rollup alternatives exist but are not native)

• Initial setup is complicated – Requires per-app Webpack configuration and shared dependency coordination

• Runtime failures are possible – If the remote is down, the host may break unless you handle fallbacks

• Version mismatch risks – Shared libs (like React) must be tightly versioned and aligned

• No automatic SSR – Requires custom hydration logic for federated components

👨🏻‍💻 Popular Use Cases

Use Module Federation when:

• You want to build a platform composed of independently deployed apps

• You need runtime module loading (not just widgets)

• You want to share design systems or UI libraries across apps

• Your team is federating complex app sections, not just components

• You want to avoid loading dependencies multiple times across apps

Other Tools & Ecosystem Additions

While iframes, Web Components, single-spa, and Module Federation are the major players in the micro-frontend arena, there’s a growing ecosystem of alternative tools and strategies. They don’t always serve as full micro-frontend methods, but still solve important pieces of the puzzle. Let’s walk through some of the less prominent, yet practical solutions that are worth your attention.

Import Maps + Native ES Modules

Import Maps allow you to define where modules are loaded from, directly in the browser. Combined with native ES module support, they enable zero-build micro frontend setups.

<script type="importmap">
{
  "imports": {
    "ui-library/": "https://cdn.example.com/ui/v1.2.3/",
    "square": "./modules/shapes/square.js"
  }
}
</script>

You might’ve noticed that it looks similar to what single-spa + SystemJS does.

Use it when:

• You want to dynamically load shared libraries (like design systems)

• You’re building federated apps without bundlers

• You’re targeting modern browsers only

Piral: Micro Frontends as Pluggable Portals

Piral is a specialized framework for building portal-based micro frontends. It provides a structured environment where micro apps (called pilets) can be plugged into a central shell (the Piral instance).

Source: https://piral.io/

This framework comes with built-in:

• Routing

• Layout orchestration

• Shared state

• Module loading

• Authentication hooks

Great for:

• Enterprise-scale portals

• Apps with lots of features teams

• Admin dashboards or CMS-heavy UIs

Luigi: Micro Frontends + SAP-style Shells

Luigi is a microfrontend framework built by SAP to enable consistent layout shells with side navigation, top bars, permissions, and more.

Source: https://luigi-project.io/

This framework comes with built-in:

• Config-driven app registration

• Automatic route activation

• Role-based access control (RBAC)

• Seamless iframe integration with a shell

Great for:

• Intranet tools

• Cloud admin panels

• Productized dashboards

Open Components

OpenComponents is a framework-agnostic way to build self-contained microservices with UI logic, registered to a central registry.

Source: https://github.com/opencomponents/oc

This framework comes with built-in:

• Server-rendered or client-rendered

• REST-like model for UI consumption

• Great CDN + registry story

Great for:

• Used when your company treats UI as deployable microservices, just like APIs.

Bit: Meet a composable architecture

Bit isn’t a micro frontend framework per se, but a component-driven development and distribution platform. It organizes source code into composable components, empowering to build reliable, scalable applications in the era of AI.

Source: https://bit.dev

Use it alongside Web Components or Module Federation to supercharge reuse. If you want to practice, they have an Official Guide on how to master Micro-Frontends with Module Federation.

It’s a great addition when:

• You want to publish reusable components across teams

• You need to manage versions, ownership, and discovery

• You’re aiming for component-first delivery, not app-first

Final Thoughts

Micro frontends offer immense power, but that power comes with architectural responsibility.

Each method we explored solves a different kind of problem:

• IFrames are secure, but come with complex communication and high isolation.

• Web Components are native, framework-agnostic, dependency-free, and perfect for reusable UI Kits

• single-spa shines when you need orchestration and multiple SPAs under one shell.

• Module Federation is the go-to for runtime code sharing and independent deployment.

• And tools like Import Maps, Piral, Luigi, and others fill in the gaps, each in their own way.

There’s no one-size-fits-all solution here, but with the right match for your team structure and product strategy, you can build apps that scale across teams, tech stacks, and time.

If you liked this guide, feel free to repost and share it with your friends, colleagues, and social network.

If you want to take your micro-frontend skills to a new level, especially around Web Components, I invite you to check out my best-selling Udemy course called “Web Components: The Ultimate Guide from Zero to Hero“.

And of course, if you have questions, feedback, or need help with your micro frontend setup, feel free to reach out to me on my social media such as LinkedIn / X / Telegram. I’m always happy to chat, connect, and help other devs build amazing things! 💚

Let’s build the IT future we could be proud of! 💪🏼 Thanks for reading — and happy decoupling! 🚀

And managers frequently view refactoring as "not a business need" until it boils over and becomes the most significant business need possible.

"Oh, our software somehow works. We can't implement any new changes. And oh, everyone is quitting because work is miserable."

In this article, I’ll walk you through the steps I use to refactor a complex codebase. We’ll talk about setting goals, writing tests, breaking up monoliths into smaller modules, verifying changes, making sure existing features still work, and keeping tabs on performance. I’ll also show you how to speed up reviews using AI tools.

By following these steps, you can turn complex, fragile code into a clean, reliable codebase your team can own.

The Issue of Technical Debt

As projects grow and evolve, technical debt increases. Code that was once functional and manageable turns into an unmaintainable mess, where even small changes become risky and time-consuming.

Despite the obvious need for cleanup, refactoring rarely gets prioritized because there's always something more urgent, new features, bug fixes, and client demands.

I’ve had conversations with engineers, many of whom are working on enterprise software and are fully aware of their codebase's code smells and inconsistencies. They dislike the situation but feel powerless to change it.

So how do we shift from a culture of writing for pure functionality to a culture that values maintainability, especially for complex codebases?

It’s usually a mistake to completely halt new feature development for a long refactoring period (except perhaps in emergencies). Business needs still exist, and putting everything on hold can create tension and lost opportunities. It’s better to find a balance so you’re still delivering value to users even as you clean under the hood.

While there is no one-size-fits-all solution, a structured approach can help teams introduce sustainable refactoring practices, even in environments where management is resistant. Let’s explore how this works.

Table of Contents:

• What is Refactoring?

• Preparing for Refactoring

  • Secure Management Buy-in

  • Ensure a Safety Net with Automated Testing

  • Identify High-Risk Areas

  • Set Clear Refactoring Goals

• Techniques for Refactoring Complex Codebases

  • 1. Identifying and Isolating Problem Areas

  • 2. Incremental vs. Big Bang Refactoring

  • 3. Breaking Down Monolithic Code

  • 4. Ensuring Backward Compatibility

  • 5. Handling Dependencies and Tight Coupling

  • 6. Testing Strategies (Safely Refactoring with Confidence)

  • 7. Refactoring Without Breaking Performance

  • 8. Automate Code Reviews with AI Tools

  • Summary

What is Refactoring?

Many people all too often use the word "refactor" when they mean a targeted rewrite.

As Martin Fowler famously said,

“Refactoring is a controlled technique for improving the design of an existing code base. Its essence is applying a series of small behavior-preserving transformations... However, the cumulative effect... is quite significant.”​

In practice, this means continuously polishing code to reduce complexity and technical debt.

While traditional software development follows a linear approach of designing first and coding second, real-world projects often evolve in ways that lead to structural decay. Refactoring counteracts this by continuously refining the codebase, transforming disorganized or inefficient implementations into well-structured, maintainable solutions.

A targeted rewrite is a focused overhaul of a specific aspect of an application, often affecting multiple parts of the codebase. It carries more risk than refactoring but is still controlled and contained.

Preparing for Refactoring

Even the most skilled refactoring effort can stall without proper preparation. Before you start moving code around, laying a foundation that will keep your work organized and your team on the same page is crucial.

Here are some steps you can take to ensure your refactoring efforts are successful.

Secure Management Buy-in

As I’ve already discussed, getting time for refactoring can be difficult in feature-driven organizations. Often, management will accept refactoring investment if you can tie it to business outcomes, faster time to market, fewer outages (which translates to happier customers), and the ability to take on new initiatives.

Make those connections explicit. For example, you could say:

“If we refactor our reporting engine now, it will make it feasible to add the analytics module next quarter, which unlocks a new revenue stream.”

Or use data:

“We spent 30% of our last sprint fixing bugs in module Y. After refactoring Y, we expect that to drop significantly, freeing time for new features.”

Business-minded arguments help justify the balance.

Ensure a Safety Net with Automated Testing

As you refactor, tests are your safety net. Before modifying a component, write characterization tests around it if they don’t exist.

# example: characterization test for a legacy function
def legacy_calculate_discount(price, rate):
    # ... complex logic you don't fully understand yet ...
    return price * (1 - rate/100) if rate < 100 else 0

def test_legacy_calculate_discount():
    # capture existing behavior
    assert legacy_calculate_discount(100, 10) == 90
    assert legacy_calculate_discount(50, 200) == 0

These tests capture the current behavior, so you’ll know if you accidentally change it. Unit tests, integration tests, and e2e tests all validate that refactoring hasn’t broken anything.

It’s often worth investing time in setting up a continuous integration pipeline so that every change triggers automated tests. This gives rapid feedback and confidence that you’re not introducing regressions. Robust testing and CI/CD enable you to move faster and refactor with peace of mind.

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with: python-version: '3.10'
      - run: pip install -r requirements.txt
      - run: pytest --maxfail=1 --disable-warnings -q

Identify High-Risk Areas

The first step is to figure out what to refactor. High-risk areas are parts of the code likely to cause bugs or slow development. Common signs include long methods, large classes, duplicate code, and complex conditional logic​.

Such code “smells” often hint at deeper design problems. Tools like static analysis can automatically flag these issues.

For example, SonarQube will mark code smells (like high complexity or long methods) that increase technical debt​. Using SonarQube or similar tools, you can generate reports on code complexity (for example, cyclomatic complexity metrics​) and find hotspots in the codebase that need more attention.

Set Clear Refactoring Goals

Before refactoring code, define the goal.

Goals must be specific and measurable. For example, you might aim to reduce a class’s size or a function’s cyclomatic complexity by a certain amount or to increase unit test coverage from 60% to 90%.

Each goal is tied to a measurable outcome: shorter methods, fewer if statements or classes with a single responsibility, faster execution for processing orders, higher test coverage, and no unused code. These targets will guide our refactoring plan and let us verify when we’ve succeeded.

Tip: Write down your refactoring goals and share them with your team. This sets expectations that you’re not adding new features in this effort, just making the code cleaner and more robust. It also helps justify the time spent by showing the benefits (like more straightforward future additions and fewer bugs).

Techniques for Refactoring Complex Codebases

1. Identifying and Isolating Problem Areas

It can be overwhelming to decide where to start refactoring a large codebase. Not every part of the code needs refactoring – some areas are delicate or rarely touched.

The most impactful refactoring efforts typically target the “problem areas”: parts of the codebase that are overly complex, error-prone, or act as bottlenecks for development and performance. Identifying these areas is a crucial first step.

Techniques for Finding Hotspots

Team knowledge & developer frustration

Don’t underestimate the value of anecdotal information from the team. Which parts of the code do developers dread working in? Often, the team’s instincts point to areas that are hard to understand or modify (for example, “the accounting module is a black box, we hate touching it”). These could be areas to improve.

In my experience, simply asking, “If you had a magic wand, which part of the code would you rewrite?” yields very insightful answers.

Code complexity metrics

Use static analysis tools to measure cyclomatic complexity, code duplication, large functions/classes, and so on. Files or modules with extremely high complexity numbers or thousands of lines are good candidates for scrutiny. But static complexity alone doesn’t tell the whole story – a file might be ugly but rarely touched.

Change frequency (Churn)

Look at version control history to see which files are often changed, especially those associated with bug fixes or incidents.

Hotspot analysis

A robust approach combines complexity and change frequency to find “hotspots.” For example, a tool or technique plotting modules by their complexity and how often they change can highlight the problematic areas. CodeScene (a code analysis tool) popularized this: hotspots are parts of the code that are highly complex and frequently modified, indicating areas where “paying down debt has a real impact”​.

If a module is a mess and developers are in it every week, improving that module will likely yield outsized benefits (fewer bugs, faster adds).

Performance bottlenecks and crashes

Some parts of the codebase become targets for refactoring because they cause frequent performance problems or outages. For instance, if a specific service or job crashes often or can’t keep up with the load, you might need to refactor it for stability.

How to Isolate Problem Areas

Once you’ve identified a hotspot or problem area, the next challenge is isolating it so you can refactor safely. In a complex system, nothing lives in complete isolation. That problematic module likely interacts with many others.

Here are strategies to isolate and tackle it:

Break dependencies (Create seams)

Michael Feathers (in Working Effectively with Legacy Code) introduced the concept of “seams” – places where you can cut into a codebase to isolate a part for testing or refactoring. This might mean introducing an interface or abstraction between components so you can work on one side independently.

For example, suppose PaymentService is tightly coupled to StripeGateway, with direct calls scattered throughout the code.

# payment_service.py

def charge_customer(order_id, amount):
    # Hardcoded dependency to Stripe
    stripe = StripeGateway()
    stripe.charge(order_id, amount)

To isolate and refactor the payment logic safely, you can introduce a PaymentProcessor interface and have PaymentService depend on that interface instead. Then, create an adapter like StripeAdapter that implements PaymentProcessor and delegates to the existing Stripe logic.

This way, you can safely refactor or even replace the Stripe integration behind the StripeAdapter without impacting PaymentService or any other module that uses it. As long as the PaymentProcessor interface is honored, the rest of the system remains unaffected.

# interfaces.py

class PaymentProcessor:
    def charge(self, order_id, amount):
        raise NotImplementedError


# stripe_adapter.py

class StripeAdapter(PaymentProcessor):
    def charge(self, order_id, amount):
        # Internally still uses Stripe
        stripe = StripeGateway()
        stripe.charge(order_id, amount)


# payment_service.py (Refactored)

class PaymentService:
    def __init__(self, processor: PaymentProcessor):
        self.processor = processor

    def charge_customer(self, order_id, amount):
        self.processor.charge(order_id, amount)

“Branch-by-abstraction”

This technique is related to the above and is often used in continuous delivery. The idea is to add a layer of abstraction (like an interface or proxy) in front of the old code, have both old and new code implementations behind it, and then gradually shift usage from the old to the new implementation. For a while, you might have a temporary state where both versions exist (perhaps toggled by a config or feature flag).

This is similar to how the strangler fig pattern works at an architectural level. It’s a bit of extra work (since you maintain two paths for a while), but it allows you to migrate functionality and fall back if needed incrementally.

Aim to identify the 20% of the code causing 80% of the problems. Focus your refactoring energy there for maximum impact. When you do, create a plan to isolate that area via abstractions, interfaces, modules, or other means so that you can work on it with minimal risk of side effects. The more you can contain the blast radius of a refactoring, the more confidently you can move forward.

2. Incremental vs. Big Bang Refactoring

One of the first strategic decisions is approaching the refactor incrementally or going for a “big bang” overhaul. In most cases, an incremental approach is preferable, but there are scenarios where more significant coordinated refactoring steps are considered.

Let’s break down what these mean:

# before: one large function with multiple responsibilities
def process_order(order):
    validate(order)
    apply_discount(order)
    save_to_db(order)
    send_confirmation(order)
    log_metrics(order)
    update_loyalty_points(order)
    # potentially more steps 

# after: refactored incrementally into clearer, smaller units
def process_order(order):
    validate(order)
    apply_discount(order)
    persist_and_notify(order)

def persist_and_notify(order):
    save_to_db(order)
    send_confirmation(order)
    log_metrics(order)
    update_loyalty_points(order)

Incremental refactoring

This means making small, manageable changes over time rather than attempting a massive overhaul in one shot. The system should remain functional at each step (even internally in transition). The advantage is risk mitigation: each small change is less likely to go wrong, and it’s easier to pinpoint and fix if it does.

Incremental delivery lets you confirm changes in production and makes diagnosing issues easier since you’re only changing one small thing at a time​. It also means the system keeps running during the refactor, so there’s less pressure to rush to “get the system back to working condition”​. If priorities shift, you can pause after some increments and still have a working product.

Big bang refactoring (Rewrite)

This is the “tear it down and rebuild” approach. You stop adding new features, possibly freeze the code for a period, and devote a considerable effort to redesigning or rewriting a significant portion (or the entirety) of the system. The idea is to emerge on the other side with a brand new, clean system.

So when (if ever) is a big bang justified? Perhaps when the existing system is truly untenable – for example, an outdated technology that must be replaced (such as a platform that can’t meet new performance or security requirements or code written in a language no longer supported). Even then, wise teams often simulate a big bang by breaking it into stages or developing the new system in parallel.

Whenever possible, favor an incremental refactoring strategy. Teams successfully pull off massive transformations by treating the big refactor as a series of mini-refactors under a shared vision.

3. Breaking Down Monolithic Code

Many complex codebases start life as a single monolithic application, one deployable, a single code project, or a tightly coupled set of modules all maintained and released together.

Over time, monoliths can become unwieldy, builds take forever, a change in one area can unintentionally affect another, and teams can be complex to scale because everyone is stepping on each other’s toes in the same code. A common refactoring challenge for senior engineers is modularising or splitting a monolith into more manageable pieces.

# define the interface
class PaymentProcessor:
    def charge(self, amount): ...

# old implementation
class LegacyProcessor(PaymentProcessor):
    def charge(self, amount):
        # original code

# new implementation behind a feature flag
class NewProcessor(PaymentProcessor):
    def charge(self, amount):
        # cleaner code

def get_processor():
    if config.feature_new_payment:
        return NewProcessor()
    return LegacyProcessor()

# usage remains the same
processor = get_processor()
processor.charge(100)

Strategies for modularization.

• Layer separation: Start by enforcing logical layer boundaries. For example, separate the user interface code from business logic and separate business logic from data access. In a messy monolith, these concerns often get mixed together. By organizing the code into layers (even within the same repository), you can limit the ripple effect of changes.

• Domain-based modularization: If your system spans multiple business domains or functional areas, consider splitting along those lines. For example, an e-commerce monolith might be separated into modules like Accounts, Orders, Products, Shipping, and so on.
  Each could become a subsystem or a package. The goal is to minimize the information these modules need to know about each other’s internals (high cohesion within modules and clear APIs between them).

• Microservices or services extraction: In recent years, the trend has been to break monoliths into microservices, independent services that communicate over APIs. This form of architectural refactoring can significantly improve independent deployability and scalability. But it’s a significant undertaking with complexities (distributed systems, network calls, and so on). If you decide to go this route, do it gradually.
  A proven method is the strangler fig pattern mentioned earlier: you pick one piece of functionality and rewrite or extract it as a separate service, redirect traffic or calls to the new service. At the same time, the rest of the monolith remains intact and iteratively does this for other pieces​.

• Modular monolith: Not every system needs to go full microservices. There’s an approach called a modular monolith, essentially structuring your single application into well-defined modules that communicate via explicit interfaces (almost like internal microservices but without the overhead of separate deployments).

This can give you many microservices' advantages (clear boundaries, separate development responsibility) while avoiding operational complexity.

• Identify shared utilities vs. truly independent components: In breaking down a monolith, some code is widely shared (like utility functions or cross-cutting concerns such as authentication). It might make sense to factor those into libraries or services first, as they will be needed by whatever other pieces you split out.

While breaking down a monolith, maintaining functionality during the transition is essential. Techniques like backward compatibility (discussed next) and thorough testing will be your safety net.

Finally, be prepared for the team workflow to change. If you move to microservices, teams might take ownership of different services, requiring more DevOps and communication across teams. If you keep a modular monolith, enforce code ownership or review rules to keep the modules from tangling up again (for example, you might restrict direct database access from one module to another’s tables, and so on).

4. Ensuring Backward Compatibility

A critical concern during large refactoring is: Will our changes break existing contracts?

In other words, can other systems, modules, or clients that rely on our code work as expected after we refactor? Backward compatibility is especially important if your codebase provides public APIs (to external customers or other teams), data persisted in a certain format, configuration files that users have written, etc.

Here are some strategies and considerations to maintain backward compatibility:

Suppose you have a widely-used function like send_email(to, subject, body). You want to refactor the internal logic to support additional features like HTML formatting, but you don’t want to break existing callers.

Instead of changing the function signature, you keep the public API unchanged and delegate to a new internal function:

# original API
def send_email(to, subject, body):
    # send mail...

# refactored internals, keep signature
def send_email(to, subject, body):
    sendv2(to=to, subject=subject, body=body)

def sendv2(to, subject, body, html=True):
    # new implementation with HTML support

The internal send_email_v2() function adds new capabilities like HTML formatting, but older code using send_email() still works without any modifications.

If you're introducing a new, improved version like send_email_v2(to, subject, body, html=True), it's good practice to:

• Mark the old version (send_email) as deprecated in documentation.

• Ensure the old version internally calls the new one.

• Give other teams time to migrate at their own pace.

Use versioning for external APIs

If your system provides an HTTP API or similar to external clients, the safest route for major changes is to version the API. Introduce a v2 API endpoint for the refactored logic, keep v1 running (maybe internally calling v2 or using a translation layer). Clients can move to v2 at their own pace.

It’s extra work to maintain two APIs temporarily, but it prevents a breaking change from angering users or causing outages. Always communicate changes clearly and provide migration guides if applicable.

Have a clear deprecation policy

Make sure there’s a policy (and communication) around how long deprecated features will be supported. For internal APIs, maybe it’s one release cycle. For external ones, maybe multiple cycles or never removal without a major version bump. A good practice is to announce deprecation early.

If you’re exposing an HTTP API, consider introducing a new versioned endpoint (for example, /api/v2/send_email) and maintain the older /api/v1/send_email temporarily. Internally, v1 might call v2 with default parameters, ensuring behavior stays consistent for existing clients.

In summary, maintain backward compatibility whenever possible, and implement a clear deprecation policy for anything you do change​.

Write adapter or compatibility layers

In some cases, you can write an adapter to bridge old and new systems. For instance, suppose you refactor the underlying data model of your application, but you still have old configuration files in the old format. Rather than forcing all those files to be rewritten immediately, you could write a small adapter that translates the old format to the new one at runtime (or during startup). This way, old data continues to work.

Test for compatibility

Include tests that specifically ensure backward compatibility. For instance, if you have a public API, keep a suite of tests using the old API contracts and run them against the refactored code, they should still pass.

In summary, ensure that as you refactor, the external behavior and contracts remain consistent. This careful approach protects your users and downstream systems, allowing you to reap the internal benefits of refactoring without causing external chaos.

5. Handling dependencies and tight coupling

One of the hairiest aspects of refactoring a large codebase is dealing with deeply interdependent code. Complex systems often suffer from tight coupling. Module A assumes details about Module B and vice versa, global variables or singletons are used all over, or a change in one place ripples through half the codebase.

Reducing coupling is a significant aim of refactoring because it makes the code more modular, meaning each piece can be understood, tested, and changed independently. So, how do we gradually loosen the coupling in a legacy system?

Let’s go over some strategies to reduce coupling.

Introduce interfaces or abstraction layers

A very effective way to decouple is to put an interface between components. For example, if you have a class that directly queries a database, introduce an interface and have the class use that instead. The underlying database code implements the interface.

# before: direct instantiation
class OrderService:
    def __init__(self):
        self.repo = OrderRepository()

# after: inject dependency
class OrderService:
    def __init__(self, repo):
        self.repo = repo

# wiring up in application startup
repo = OrderRepository(db_conn)
service = OrderService(repo)

Now, that class no longer depends on how the data is fetched. Applying the dependency inversion principle depends on abstractions, not concretions.

Use dependency injection

Once you have interfaces, use dependency injection to supply concrete implementations. Many frameworks support DI containers, or you can do it manually (passing in dependencies via constructors). Dependency injection means code A doesn’t instantiate code B itself – instead, B is passed into A.

This approach also makes unit testing easier (you can inject mock dependencies).

Facades or wrapper services

If a particular subsystem is heavily entangled with others, consider creating a Facade, an object that provides a simplified interface to a larger body of code. Other parts of the system are then called the Facade, not the many internal methods of the subsystem. Internally, the subsystem can be refactored (even split into smaller pieces) as long as the Facade’s outward interface remains consistent.

This is similar to how microservices work (other services don’t care how one service is implemented internally – they just call its API), but you can do it in-process, too.

Gradual replacement (Parallel Run)

If a specific component is to be replaced with a new implementation, it can help to run them in parallel for a while. For instance, if you have a spaghetti module that you want to redo correctly, you could leave the spaghetti code in place for legacy calls but start routing new calls to the new module.

The result is a codebase where changes in one area (hopefully) won’t unpredictably break another, a key property of a maintainable system.

6. Testing Strategies (Safely Refactoring with Confidence)

A robust testing strategy will give you the confidence to make sweeping changes because you’ll know quickly if something important breaks. Here’s how to approach testing in the context of a large refactoring:

Establish a baseline with regression tests

Before you even begin refactoring a particular component, make sure you have tests that cover its current behavior. You're lucky if the codebase already has a good test suite, but many legacy systems have inadequate tests.

One of the first tasks in those cases is often writing characterization tests. A characterization test is a test that documents what the system currently does, not what we think it should do​.

As Feathers says, “a characterization test is a test that characterizes the actual behavior of a piece of code.” This allows you to take a snapshot of what it does and ensure that it doesn’t change​.

This gives you a safety net so you can refactor with confidence that you’re not introducing regressions​. Use automated test suites to help things run smoothly (unit, integration, end-to-end).

Continuous integration (CI)

It is highly recommended that testing be integrated into a CI pipeline that runs on every commit or merge. This way, you catch a bug during refactoring as soon as you introduce it, tightening the feedback loop.

Canary releases and feature flags

Beyond pre-release testing, consider strategies for safely deploying refactored code. A canary release involves rolling out the change to a small subset of users or servers first, observing it, and then gradually expanding​.

This is great for catching issues that tests might miss (for example, performance issues or edge cases in production data). If the canary looks good (no errors, metrics are healthy), you proceed to full rollout. If not, you rollback quickly—with only a small impact scope.

Performance and load testing

If performance is a concern, incorporate performance tests into your strategy. This can be done in a staging environment. You might reconsider your approach or optimize the new code if you see a significant regression.

Testing legacy code lacking tests

If you’re dealing with a part of the system with zero tests (not uncommon in older code), prioritize getting at least some coverage there. There are also techniques like approval testing (where you generate output and have a human approve it as correct, then use that as a baseline for future tests). The key is not to refactor entirely in the dark; give yourself at least a flashlight in the form of tests!

In sum, a strong testing strategy is non-negotiable for refactoring complex systems. It’s your safety net, early warning system, and guide to know that your “cleanup” hasn’t broken anything vital.

7. Refactoring Without Breaking Performance

A common concern when refactoring is whether these cleaner code changes will make my system slower or more resource-hungry. Ideally, refactoring is about the internal structure and shouldn’t change external behavior, and performance is part of the behavior.

In theory, performance should remain the same if you don’t change algorithms or data structures in a way that affects complexity.

In practice, though, performance can be inadvertently affected by refactoring. The new code may be more readable but uses more memory, or perhaps a critical caching mechanism was removed in the spirit of simplicity.

Senior engineers need to be mindful of performance-sensitive parts of the system when refactoring and take steps to avoid regressions (or even improve performance where possible).

Here’s how to refactor with performance in mind:

Identify performance-critical code paths

Not all codes are equal regarding performance impact. If you refactor them, treat it almost like a functional change: you must re-measure performance afterwards. You have more leeway for parts of the code that run rarely or are not bottlenecks.

Use profiling before and after

A profiler is a tool that measures where time is spent in your code or how memory is allocated. It’s beneficial to run a profiler on the code before refactoring a module to see how it behaves, and then run it after to compare. If you see, for example, that after refactoring, a function now shows up as taking 30% of execution time (when it was negligible before), that’s a red flag. Maybe the new code calls it more times than before.

import cProfile, pstats
from mymodule import slow_function

def profile(fn):
    profiler = cProfile.Profile()
    profiler.enable()
    fn()
    profiler.disable()
    stats = pstats.Stats(profiler).strip_dirs().sort_stats('cumtime')
    stats.print_stats(10)

# run before refactor
profile(lambda: slow_function())

# after you refactor slow_function(), re-run and compare stats

When possible, improve performance through refactoring

On the flip side, refactoring can help performance.

For example, by refactoring duplicated code into one place, you can use better caching in that one place. So, watch for performance improvement opportunities that arise naturally as you refactor.

Performance should be treated as part of the “external behavior” that needs to be preserved in a good mindset. Refactoring should ideally not make things slower for users. To ensure that, incorporate performance checks into your plan, especially for critical sections. Measure, don’t guess. The end goal is a codebase that is both clean and fast enough.

8. Automate Code Reviews with AI tools

Refactoring code is an ongoing process, not a one-time event – AI code review tools help enforce clean-code standards, catch smells early, and reduce the repetitive tasks that can bog down human reviewers. This frees your engineers to focus on deeper architectural or domain-specific issues.

One powerful option is CodeRabbit, an AI-driven review platform designed to cut review time and bugs in half.

Here’s how it works and why it can boost your refactoring workflow:

AI-powered contextual feedback

CodeRabbit analyzes pull requests line by line, applying both advanced language models and static analysis under the hood. It flags potential bugs, best-practice deviations, and style issues before a human opens the PR.

Some other features include:

• Auto-generated summaries and 1-click fixes – Summarize large PRs and apply straightforward fixes instantly.

• Real-time collaboration and AI chat – Chat with the AI for clarifications, alternate code snippets, and instant feedback.

• Integrates with popular dev platforms – Supports GitHub, GitLab, and Azure DevOps for seamless PR scanning.

CodeRabbit even has a free AI code reviews in VS Code and with this VS Code extension, you can get the most advanced AI code reviews directly in your code editor, saving review time, catching more bugs, and helping you in refactoring.

Summary

Refactoring a complex enterprise codebase is like renovating a large building while people still live in it without collapsing the structure.

Refactoring should be an ongoing process. You prevent the codebase from decaying by incorporating these practices into your regular development (perhaps allocating some time each sprint for refactoring or doing it opportunistically when touching your code). Each minor refactoring should not be too complex, and the cumulative effect is significant.

As Martin Fowler puts it, a series of small changes can lead to a significant improvement in design.

That's it for this blog. I hope you learned something new today.

If you want to read more interesting articles about developer tools, React, Next.js, AI and more, then I'll encourage you to checkout my blog.

Some of the new and interesting articles I've written in the last 24 months.

• Cursor vs Windsurf

• How to Implement Role-Based Access Control in Next.js

• AI Code Reviewers vs Human Code Reviewers

• How to Build a Custom Video Conferencing App with Stream and Next.js

• How to Perform Code Reviews in Tech – The Painless Way

You can get in touch if you have any questions or corrections. I’m expecting them.

And if you found this blog useful, please share it with your friends and colleagues who might benefit from it as well. Your support enables me to continue producing useful content for the tech community.

Now it’s time to take the next step by subscribing to my newsletter and following me on Twitter.