One of the most intuitive features in modern design tools is the ability to select and manipulate multiple objects simultaneously. Whether you're moving several graphics together, changing their size or deleting a group of items at once, multiselect dramatically improves workflow efficiency.

In this article, we'll explore how we implemented multiselect functionality in the Ablo editor, the challenges we faced, and why this feature makes the editing experience so much more powerful and intuitive.

2. Before Multiselect: The Single-Selection Era

Previously, the Ablo editor operated in a single-selection mode. Users could only interact with one object at a time on the canvas. This meant that common workflows like:

• Moving multiple graphics together

• Deleting a group of objects

• Copying multiple items at once

...required users to perform these operations one object at a time, which was tedious and time-consuming. Each operation required clicking an object, performing the action, then repeating for the next object.

3. How Single Selection Worked Under The Hood

In the single-selection implementation, object selection was handled through mouse event listeners. When a user clicked on the canvas, the system would:

• Detect the click target: On mouse:up events, the code checked if the click hit an object (e.target)

• Set the active object in Canvas: If an object was clicked and it was selectable, it would be set as the active object:

  •     canvas.on('mouse:up', function (e) {
          if (e.target?.selectable) {
             canvas.setActiveObject(e.target);
             canvas.renderAll();
          }
        });
    

• Update React state: The active object was then stored in React state and used throughout the editor.

  •     const activeObj = canvas.getActiveObject();
        setActiveObject(activeObj || null);
    

• Handle deselection: Clicking on empty canvas space would deselect the current object, clearing the active state

This approach worked well for single-object interactions, but it meant that selecting multiple objects required a sequential process: click object A, perform action, click object B, perform action, and so on. There was no way to select multiple objects simultaneously and operate on them as a group.

4. The Solution: Fabric.js ActiveSelection

Fabric.js, the powerful canvas library that powers our editor, provides a built-in solution for multiselect through the ActiveSelection class. This class represents a temporary group of selected objects that can be manipulated together without permanently grouping them.

The key insight is that ActiveSelection behaves like a regular fabric object in many ways, it can be moved, scaled, rotated, and transformed, but it's actually a container that holds references to multiple objects. When you perform operations on an ActiveSelection, fabric.js intelligently applies those operations to all contained objects.

4.1. Enable Selection on fabric.js canvas

The first step was to enable canvas selection specifically for desktop users. In our canvas initialization code, we conditionally enable selection based on the device type:

  const isCanvasSelectionEnabled = isSelectionEnabled && !isMobile;

  canvas = new fabric.Canvas(`${canvasName}`, {
    width,
    height,
    selection: isCanvasSelectionEnabled,
    ...
  });

This ensures that:

• Desktop users get the full multiselect experience with drag-to-select and modifier key support

• Mobile users maintain the touch-friendly single-tap selection behavior

• The feature can be toggled if needed via the isSelectionEnabled parameter for most mini-versions of the editor

4.2. Why fabric.js `getActiveObject()` can Handle both Single & Multi Select

A key aspect of fabric.js's selection system is that canvas.getActiveObject() can return either a single fabric.Object or a fabric.ActiveSelection, depending on how many objects are currently selected. This is handled automatically by fabric.js:

• Single object selected: When a user clicks on one object, getActiveObject() returns that object directly (e.g., fabric.Image, fabric.IText, etc.)

• Multiple objects selected: When a user drags to select multiple objects or uses modifier keys to add objects to the selection, fabric.js automatically creates an ActiveSelection instance that wraps all selected objects. In this case, getActiveObject() returns the ActiveSelection container.

This design means we don't need to manually track which objects are selected, as fabric.js manages the selection state internally. When selection is enabled on the canvas (selection: true), fabric.js handles the complexity of:

• Creating selection rectangles when dragging

• Managing modifier key behavior (Shift + Click for adding to selection)

• Automatically wrapping multiple selections in an ActiveSelection

• Returning the appropriate type based on selection count

This is why we can simply call canvas.getActiveObject() anywhere in our code and check the type. Fabric.js has already done the heavy lifting of managing the selection state.

4.3. Type System Updates

To properly handle multiselect throughout our codebase, we updated our type definitions to recognize ActiveSelection as a valid active object type:

  const [activeObject, setActiveObject] = useState<fabric.Object | fabric.ActiveSelection | null>(null);

4.4. Detecting and Normalizing Selections

Throughout the codebase, we use a consistent pattern to detect when the user has selected multiple objects and normalize them for processing:

const isMultiSelect = activeObject instanceof fabric.ActiveSelection;
const objectsToProcess: fabric.Object[] = isMultiSelect
    ? activeObject.getObjects()
    : [activeObject];

The key insight of this pattern is that it serializes the selection into an array format, regardless of whether we're dealing with a single object or multiple objects. This normalization allows us to:

• Check if we're dealing with a multiselect using instanceof fabric.ActiveSelection

• Extract the individual objects, either from the ActiveSelection container or wrap the single object in an array

• Process all objects uniformly using array methods like forEach, map, or filter

By converting both cases into an array, we can write operation logic once that works for both single and multiple selections, making the code more maintainable and consistent.

5. The Challenges: Not So Easy As It Sounds

5.1. Mobile Considerations

One of the first decisions we had to make was how multiselect should work on mobile devices. We decided to move fast and ship multiselect as a Desktop-Only feature for the first version.

Why? Mobile devices have different interaction patterns, touch gestures, smaller screens, and different user expectations. The drag-to-select behavior that works so well on desktop with a mouse doesn't translate naturally to touch interfaces and might conflict with like pan gestures.

By keeping multiselect desktop-only initially, we could:

• Focus on perfecting the desktop experience first

• Avoid complicating the mobile touch interactions

• Maintain the existing, optimized mobile selection behavior

This decision allowed us to ship a polished desktop feature faster while keeping the door open for future mobile enhancements if user feedback indicates a need.

5.2. Operation Consistency

One of the main challenges was ensuring that operations like copy, delete, and layer management work correctly with multiple objects. For example, when copying multiple objects, we need to preserve their relative positions and transformations.

Solution: We handle this by checking for multiselect and processing all objects in the selection one by one:

  const handleRemoveActiveObject = () => {
    const activeObject = canvas.getActiveObject();

    const objectsToProcess =
      activeObject instanceof fabric.ActiveSelection ? activeObject.getObjects() : [activeObject];

    objectsToProcess.forEach((obj: fabric.Object) => {
      canvas.remove(obj);
    });

    canvas.discardActiveObject();
    canvas.renderAll();

    saveState();
  };

This pattern respects the DRY principle by normalizing the selection into an array format upfront. Instead of having conditional checks scattered throughout the codebase, e.g. checking if (isMultiSelect) in every operation, we perform a single check at the beginning and then process all objects uniformly.

5.3. Complex Operations and Scope Management

Not all operations make sense or are feasible with multiselect. Some features, like cropping, are inherently single-object operations that don't translate well to multiple selections.

Decision 1: We left certain operations out of scope for the first version. For example, the crop tool is disabled when multiple objects are selected:

Decision 2: Some operations like copying, need a totally different implementation for single & multiselect and can’t be processed by the exact same algorithms.

6. Why It’s Awesome

A. Intuitive Desktop Experience: Multiselect works exactly as users expect from modern design tools. You can:

• Drag to select: Click and drag on the canvas to create a selection rectangle

• Modifier keys: Hold Shift and click to add objects to your selection

• Visual feedback: Selected objects are clearly highlighted with selection handles

This matches the behavior users are familiar with from modern tools like Figma.

B. Workflow Efficiency: The time savings are significant. Consider a scenario where you need to:

• Move 5 graphics to a new position

• Delete 4 unwanted objects

Before: 9 separate operations (select, act, repeat), After: 2 operations (multiselect, act, done) ###

C. Preserves Relationships and Alignment: One of the most powerful aspects of multiselect is how it maintains the spatial relationships between objects. When you select multiple elements and move them together, their relative positions are preserved perfectly.

7. Conclusion

The multiselect feature represents a significant improvement in the Ablo editor's usability. By leveraging fabric.js's ActiveSelection class and thoughtfully handling edge cases, we've created an intuitive, powerful feature that matches user expectations from modern design tools.

The implementation demonstrates how a well-designed library feature (fabric.js's ActiveSelection) can be integrated into a complex application. The result is a feature that feels natural, saves users time, and makes the editor more powerful without adding complexity to the user interface.

SpaceRunners has a design tool where artists can create custom designs in a limited drawing area on any physical object. We already described the core concepts of the tool in previous articles on this blog. A core feature that every design tool must have by default is cropping. However, there's no native cropping feature in Fabric.js where one can just call a few functions and call it a day. We had to implement it ourselves using several steps. This entire process has sparse and incomplete documentation online. This blog post will try to give practical tips to anyone who encounters the same problems.

The basic idea of cropping in Fabric.js is to create a crop mask shape when you initiate the crop and then let the user move the mask around the drawable area. The user can position the mask to the exact area to be cropped and then confirm the action. Confirmation can be done by any combination of keys, clicks, or just a button that appears somewhere in the UI. Whatever is inside the mask will stay on the canvas and whatever is left out will be removed. The crop mask is applied by setting it as the clip path of the original image. The canvas is then exported to a data URL. The clip path is a Fabric.js concept that lets the user specify which part of the canvas is visible in the browser or when exported as an image output. This is the basic idea of how cropping works. The following sections will describe the process in detail together with some code examples.

Crop Mask

In our design tool, the crop is initiated by selecting an image and clicking on a specialized “Crop” icon in the toolbar, as displayed in the picture below:

After the crop is initiated, the design tool offers different crop shapes that can be applied to the image. Imagine this shape as a mold on an image. In the image below, which has a rectangle crop shape, you can see the rectangle crop mask over the image. After applying the crop mask, everything inside this rectangle marked by the white dots will stay on the canvas and everything else will get cropped out.

If we apply a heart shape you’ll notice how the crop mask will allow you to cut out heart shapes from the original image:

Our supported crop shapes are Rectangle, Circle, Rounded Rectangle, Heart, and Star. Fabric.js already has native shapes for everything except the Heart shape. For custom shapes such as Heart or whatever else you may want to use, you can use Fabric.js's Path object that takes an SVG path. When working with SVG icons, you must make sure that you include just the path and not the entire SVG, and that it's properly formatted and has just a single path and not embedded images. Here's the code that shows how we generate the crop mask based on the selected shape:

const heartSVGPath =
  'M 272.70141,238.71731 \
      C 206.46141,238.71731 152.70146,292.4773 152.70146,358.71731  \
      C 152.70146,493.47282 288.63461,528.80461 381.26391,662.02535 \
      C 468.83815,529.62199 609.82641,489.17075 609.82641,358.71731 \
      C 609.82641,292.47731 556.06651,238.7173 489.82641,238.71731  \
      C 441.77851,238.71731 400.42481,267.08774 381.26391,307.90481 \
      C 362.10311,267.08773 320.74941,238.7173 272.70141,238.71731  \
      Z ';

const CropMaskProps = {
  isCropMask: true,
  fill: 'rgba(0,0,0,0.3)',
  stroke: 'black',
  opacity: 1,
  originX: 'left',
  originY: 'top',
  hasRotatingPoint: false,
  transparentCorners: false,
  cornerColor: 'white',
  cornerStrokeColor: 'black',
  borderColor: 'black',
  cornerSize: 20 * 3,
  padding: 0,
  height: 150,
  width: 150,
  cornerStyle: 'circle',
  borderDashArray: [5, 5],
  excludeFromExport: true,
};

export const getCropMaskShape = (
  shapeName: CropShape,
  width: number,
  left: number,
  top: number
) => {
  let shape;

  if (shapeName === CropShape.RECTANGLE) {
    shape = new fabric.Rect({ ...CropMaskProps, left, centeredScaling: true, top });
  } else if (shapeName === CropShape.CIRCLE) {
    shape = new fabric.Circle({
      ...CropMaskProps,
      width: undefined,
      height: undefined,
      radius: width / 2,
    });
  } else if (shapeName === CropShape.ROUNDED_RECTANGLE) {
    shape = new fabric.Rect({
      ...CropMaskProps,
      rx: 20,
      ry: 20,
    });
  } else if (shapeName === CropShape.STAR) {
    shape = new fabric.Star({
      ...CropMaskProps,
      width: 200,
      height: 200,
    });
  } else if (shapeName === CropShape.HEART) {
    shape = new fabric.Path(heartSVGPath, {
      ...CropMaskProps,
      width: 200,
      height: 200,
    });
  }

  shape
    .scaleToWidth(width)
    .set({
      left,
      centeredScaling: true,
      top,
    })
    .setCoords();

  return shape;
};

Another important consideration that comes into effect at the end of cropping is that you must use similar logic to get the applied crop mask that will be used as a clip path to cut out the cropped area and remove the remainder. The original crop mask, marked by white circles as shown in the previous images, is draggable and also resizable. After the user performs any of these operations and decides on the final look of the mask, we must call another function that will take the coordinates of the live mask together with its absolute position on the canvas and then generate a new shape that is used just for cropping. Here's the code that achieves just that:

export const getAppliedCropMask = (shapeName: CropShape, croppingMask: CanvasObject) => {
  const commonProps = {
    left: croppingMask.left,
    top: croppingMask.top,
    originX: 'left',
    originY: 'top',
    absolutePositioned: true,
  };

  let cropMask;

  if (shapeName === CropShape.RECTANGLE) {
    cropMask = new fabric.Rect({
      ...commonProps,
      width: croppingMask.getScaledWidth(),
      height: croppingMask.getScaledHeight(),
    });
  } else if (shapeName === CropShape.CIRCLE) {
    cropMask = new fabric.Circle({
      ...commonProps,
      radius: croppingMask.radius * croppingMask.scaleX,
    });
  } else if (shapeName === CropShape.ROUNDED_RECTANGLE) {
    cropMask = new fabric.Rect({
      ...commonProps,
      rx: croppingMask.rx,
      ry: croppingMask.ry,
      width: croppingMask.getScaledWidth(),
      height: croppingMask.getScaledHeight(),
    });
  } else if (shapeName === CropShape.STAR) {
    cropMask = new fabric.Star({
      ...commonProps,
      width: croppingMask.getScaledWidth(),
      height: croppingMask.getScaledHeight(),
    });
  } else if (shapeName === CropShape.HEART) {
    cropMask = new fabric.Path(heartSVGPath, {
      ...commonProps,
      originX: 'left',
      originY: 'top',
    });

    cropMask.scaleToWidth(croppingMask.getScaledWidth());
  }

  return cropMask;
};

Applying the mask

After the mask is positioned at the desired place and scaled to the desired dimensions, the user can confirm the crop. At that point, we must perform a series of operations that will generate a new cropped output. Here's the code, with explanations of each line below it:

const cropMask = getAppliedCropMask(shapeToUse, croppingMask);

imageToCrop.clipPath = cropMask;

canvas.remove(croppingMask);
removeDrawingArea(canvas);

canvas.renderAll();

const cropped = new Image();

const backgroundImage = canvas.backgroundImage;
const overlayImage = canvas.overlayImage;

canvas.backgroundImage = null;
canvas.overlayImage = null;

const originalViewportTransform = canvas.viewportTransform;

canvas.viewportTransform = [1, 0, 0, 1, 0, 0];

cropped.src = canvas.toDataURL({
  left: cropMask.left,
  top: cropMask.top,
  width: cropMask.width * cropMask.scaleX,
  height: cropMask.height * cropMask.scaleY,
  multiplier: 5,
  format: 'png',
  quality: 0.99,
});

canvas.viewportTransform = originalViewportTransform;

canvas.backgroundImage = backgroundImage;
canvas.overlayImage = overlayImage;

cropped.onload = function () {
  const image = new fabric.Image(cropped);

  image.left = cropMask.left + (cropMask.width * cropMask.scaleX) / 2;
  image.top = cropMask.top + (cropMask.height * cropMask.scaleX) / 2;
  image.aiImage = activeObject.aiImage;
  image.setCoords();
  image.scaleToWidth(cropMask.width * cropMask.scaleX);

  image.set('radius', (cropMask.width * cropMask.scaleX) / 2);
  image.set('originX', 'center');
  image.set('originY', 'center');

  canvas.add(image);
  canvas.remove(imageToCrop);
  canvas.discardActiveObject();

  onCrop(image);
};

setCroppingMask(null);
setImageToCrop(null);

Here are the steps with explanations:

1. const cropMask = getAppliedCropMask(shapeToUse, croppingMask);
imageToCrop.clipPath = cropMask;

   - This gets the crop mask absolutely positioned on the canvas that will be used to tell the image output function which part of the original canvas to keep.

2.  canvas.remove(croppingMask);
    removeDrawingArea(canvas);
   
    canvas.renderAll();
   
    const cropped = new Image();
   
    const backgroundImage = canvas.backgroundImage;
    const overlayImage = canvas.overlayImage;
   
    canvas.backgroundImage = null;
    canvas.overlayImage = null;
   

This code removes from the original canvas all elements that won't be in the output. For example, it removes the drawing area lines and background/overlay images (these are the template images). This is all temporary until the clipped canvas is exported. This also removes the draggable cropping mask and saves the original background and overlay images so they can be restored after clipping.

3.  const originalViewportTransform = canvas.viewportTransform;
   
    canvas.viewportTransform = [1, 0, 0, 1, 0, 0];
   

   One tricky thing is that we must also adjust the canvas viewport at this step while preserving the original viewport. That's why we use the viewportTransform property on the canvas that is defined like this in the source docs:

   /**

   • The transformation (a Canvas 2D API transform matrix) which focuses the viewport

   • @type Array

   • @example Default transform

   • canvas.viewportTransform = [1, 0, 0, 1, 0, 0];

   • @example Scale by 70% and translate toward bottom-right by 50, without skewing

   • canvas.viewportTransform = [0.7, 0, 0, 0.7, 50, 50]; */ viewportTransform: TMat2D; **/

4.  cropped.src = canvas.toDataURL({
      left: cropMask.left,
      top: cropMask.top,
      width: cropMask.width * cropMask.scaleX,
      height: cropMask.height * cropMask.scaleY,
      multiplier: 5,
      format: 'png',
      quality: 0.99,
    });
   
    canvas.viewportTransform = originalViewportTransform;
   
    canvas.backgroundImage = backgroundImage;
    canvas.overlayImage = overlayImage;
   

   The canvas.toDataURL function generates an image from the area on the canvas that was defined by the crop mask. Then we set it as the src for a new Image element. This new Image element will be used to replace the original one. After calling the toDataURL() function, we can restore the viewport and the background and overlay images so that the user can continue using the canvas normally. One important thing here is that this operation is so fast that the user doesn't see any visual effects.

5.  cropped.onload = function () {
      const image = new fabric.Image(cropped);
   
      image.left = cropMask.left + (cropMask.width * cropMask.scaleX) / 2;
      image.top = cropMask.top + (cropMask.height * cropMask.scaleX) / 2;
      image.aiImage = activeObject.aiImage;
      image.setCoords();
      image.scaleToWidth(cropMask.width * cropMask.scaleX);
   
      image.set('radius', (cropMask.width * cropMask.scaleX) / 2);
      image.set('originX', 'center');
      image.set('originY', 'center');
   
      canvas.add(image);
      canvas.remove(imageToCrop);
      canvas.discardActiveObject();
   
      onCrop(image);
    };
   

   The last step is to position the new Image element at the exact origin where the crop mask was so that the cropped element stays in the same place and doesn't jump around. You'll notice that all the dimensions and coordinates of the image are set according to the crop mask counterparts. Then we add the cropped image to the canvas and remove the original one, while calling any handlers that will persist this new state on the backend, but that's unrelated to the canvas.

Conclusion

In this blog post we demonstrated how to implement the cropping operation on a Fabric.js canvas and also how to work with custom shapes. It’s very important to get all the details right because even one small mistake can make the elements go out of bounds or have wrong proportions. You can see the full source code for our entire design tool in our open sourced repository:

https://github.com/Space-Runners/ablo.ai/pulls

If you follow all of these steps and cross reference your implementation with our publicly available code you’ll get it right. The best approach would be to work backwards by first implementing our working implementation and then adjusting it piece by piece to fit your needs.

On the backend, we use NestJS, and we rely on @nestjs/swagger to generate OpenAPI definitions directly from code annotations. Like many teams, we initially treated Swagger primarily as a documentation tool. Swagger UI became the default reference point for frontend developers, and we maintained a Postman collection for testing and exploration. While this setup worked, it positioned our API definitions as a reference rather than a source of truth.

As the team grew and we started delivering features at a faster pace, we also found ourselves frequently updating and refactoring existing logic. This rapid development cycle made it increasingly difficult to track API changes and catch breaking updates early. Without a strongly enforced contract between backend and frontend, small changes could slip through unnoticed, leading to inconsistencies that were time-consuming to debug and reduced overall development confidence.

This post explains how we moved from “Swagger UI as documentation” to automated OpenAPI generation and consumption across environments, and how that shift fundamentally improved our API reliability, frontend integration, and overall developer experience.

Our Setup

On the backend, our architecture is built heavily around NestJS. We use @nestjs/swagger to generate OpenAPI definitions directly from decorators and annotations in our codebase. For request validation and data transformation, we rely on class-validator and class-transformer, which gives us strong runtime guarantees for incoming data. We manually defined DTOs for most endpoints, but this practice was not consistently enforced across the codebase. In many cases, we had well-defined input types and validations, but response schemas were either loosely defined or missing altogether.

On the frontend, we maintained our own TypeScript interfaces to represent backend responses. These types were manually updated and not automatically synchronized with the backend. As the API evolved, this led to gaps: some fields were missing, others were deprecated but still referenced, and certain commonly used entities existed in multiple slightly different definitions. API requests were constructed manually, along with response type casting, and frontend-side validation was minimal.

This setup worked in the early stages, but as the number of endpoints and feature iterations increased, the lack of a single, enforced API contract between backend and frontend started to create friction and uncertainty across teams.

@ApiOperation({ description: 'Get list of brands with paginantion' })
@ApiQuery({ type: GetBrandsQuery })
@ApiResponse({
  status: HttpStatus.OK,
  type: BrandDto[]
})
@UseGuards(UserGuard)
@ApiSecurity('auth')
@Get()
@UsePipes(new ValidationPipe())
async getBrand(
  @Request() req: UserAuthRequest,
  @Query() query: GetBrandsQuery,
): Promise<BrandDto[]> {
  // Service Calls
}

Automating API Client Generation

One of the key decisions we made was to keep the backend changes minimal. We didn’t introduce any new packages or tooling on the backend. Since we were already using @nestjs/swagger, all the information we needed was already there. Instead, we exposed a new internal endpoint that returns the JSON version of our OpenAPI 3.0 specification. To secure this endpoint, we added a simple header-based secret check, ensuring that the schema is only accessible to internal tooling. This approach allowed us to treat the OpenAPI definition as a first-class artifact of our backend without changing how developers write endpoints. The backend continues to generate the schema from annotations, but now it can also be consumed programmatically.

const allDocs = SwaggerModule.createDocument(
  app,
  new DocumentBuilder()
    .setTitle('Ablo API')
    .build(),
  { include: [...publicModules, ...privateModules] }
)
app.use('/', (req: Request, res: Response) => {
  if (req.headers['secret'] !== SECRET) {
    return res.status(401).send({ message: 'Unauthorized' })
  }
  res.setHeader('Content-Type', 'application/json')
  res.send(allDocs)
})

On the frontend, we introduced swagger-typescript-api to convert the OpenAPI JSON schema into fully typed TypeScript API clients and models. This tool generates request functions, response types, and shared models directly from the OpenAPI definition, removing the need for manual type maintenance. The generated output becomes the single source of truth for frontend–backend communication.

To make this process repeatable and easy to run, we added a small set of NPM scripts to our frontend project. These scripts fetch the latest OpenAPI schema from the backend, format it, and generate TypeScript definitions automatically:

// package.json
{
  "api": "npm run api:fetch && npm run api:format && npm run api:generate",
  "api:fetch": "curl -s $API_DOCS_URL -o ./src/api/docs.json",
  "api:format": "prettier --write ./src/api/docs.json",
  "api:generate": "npx swagger-typescript-api generate --path ./src/api/docs.json -o ./src/api"
}

Once generated, the API is consumed through a single, centralized client instance. This client handles base configuration and shared security concerns, such as authentication headers, so individual API calls remain clean and consistent:

// src/api/index.ts
const AbloAPI = new Api({
  baseUrl: Config.API_URL,
  securityWorker: (data) => {
    return {
      headers: {
        Authorization: `Bearer ${data?.token}`,
      },
    };
  },
});

With this setup in place, consuming backend APIs on the frontend becomes a simple, type-safe function call. For example, fetching brands no longer requires manually constructing requests or maintaining separate response types:

// src/pages/brand.ts
const brands = await AbloAPI.brands.brandControllerFindAll({
  isFeatured,
  limit,
  skip,
});

All request and response definitions are automatically generated inside Api.ts. Each endpoint includes typed query parameters, return types, and metadata derived directly from the OpenAPI schema:

// src/api/Api.ts
...
brands = {
  /**
   * Get list of brands with paginantion
   *
   * @tags Brands
   * @name BrandControllerFindAll
   * @request GET:/brands
   */
  brandControllerFindAll: (
    query: {
      active: boolean;
      limit: number;
      skip: number;
    },
    params: RequestParams = {},
  ) =>
    this.request<BrandDto[], any>({
      path: `/brands`,
      method: "GET",
      query: query,
      format: "json",
      ...params,
    }),
...

Challenges During Adoption

Challenge 1: Non-Standard Endpoint Definitions on the Backend

Our first major obstacle was consistency on the backend. Although we were already generating OpenAPI definitions through @nestjs/swagger, our controller implementations were not standardized. Over time, endpoints accumulated a large number of decorators often applied inconsistently across controllers. To solve this, we introduced a single, standardized decorator that encapsulates the full endpoint definition: routing method and path, Swagger response definitions, request body/query/param metadata, guards, roles, and additional decorators. Below is the core implementation of our EndpointDefinition decorator. It converts a single definition object into the appropriate NestJS and Swagger decorators and applies them via applyDecorators:

// src/endpoint/index.ts
export function EndpointDefinition(
  definition: EndpointDefinition
): MethodDecorator {
  const decorators: Array<
    ClassDecorator | MethodDecorator | PropertyDecorator
  > = []
  switch (definition.method) {
    case HttpMethod.get:
      decorators.push(Get(definition.path))
      break
    ...
  }
  definition.responses.forEach(response =>  decorators.push(ApiResponse(response)))
  if (definition.body) decorators.push(ApiBody(definition.body))
  if (definition.query) decorators.push(ApiQuery(definition.query))
  if (definition.params) decorators.push(ApiParam(definition.params))
  decorators.push(ApiOperation({ description: definition.description }))
  decorators.push(UseGuards(...definition.guards))
  decorators.push(...definition.extra)
  return applyDecorators(...decorators)
}

Once this abstraction was in place, controller methods became significantly easier to scan and maintain. For example, the getBrands endpoint moved from a long list of annotations into a single reusable definition that fully describes the endpoint contract:

// src/definitions/brand.ts
export class GetBrandsResponse extends BrandDto {}
export class GetBrandsQuery {
  // Properties for creating a brand
}

export const GetBrandsDefinition = EndpointDefinition({
  method: HttpMethod.get,
  path: '/brands',
  description: 'Get list of brands with paginantion',
  guards: [UserGuard],
  responses: [
    { status: HttpStatus.CREATED, type: GetBrandsResponse, isArray: true }
  ],
  extra: [UsePipes(new ValidationPipe())]
})

// src/controllers/brand.ts
@GetBrandsDefinition
async getBrand(
  @Request() req: UserAuthRequest,
  @Query() query: GetBrandsQuery,
): Promise<GetBrandsResponse[]> {
  // Service Calls
}

This pattern gave us two immediate benefits. First, controllers became cleaner and more uniform, which reduced review overhead and made it easier to spot missing pieces. Second, the OpenAPI schema quality improved because endpoint metadata was consistently defined in one place.

Challenge 2: Adopting Generated API Types on the Frontend

The second major challenge emerged on the frontend once we started consuming the generated OpenAPI types. Before this change, we relied on a small set of manually maintained TypeScript interfaces to represent most backend entities. These types were shared across multiple endpoints, pages, and components, and over time they drifted away from the actual API behavior. In particular, many fields that were optional in practice were not marked as optional in TypeScript, which masked inconsistencies until runtime.

When we switched to using the generated API definitions, these mismatches surfaced immediately as TypeScript errors. The compiler started flagging missing fields, incorrect assumptions, and invalid type usage across the application. While this was ultimately a positive outcome, it made the initial adoption phase challenging, especially for entities that were reused extensively across the UI.

To manage this, we avoided a big-bang migration. Instead, we updated the frontend incrementally, focusing on one entity at a time. For each entity, we aligned components, pages, and data flows with the generated types before moving on to the next. This was particularly time-consuming for core entities that appeared in multiple views and business flows, but it allowed us to make progress without blocking feature development.

As a result, the frontend currently uses a mix of manually defined types and generated API types. While this is not the final state we’re aiming for, it provides a practical transition path. Our long-term goal is to rely entirely on generated types as the single source of truth, but we expect this migration to happen gradually as the codebase continues to evolve.

Results

Improved API Standardization and Contract Quality

Standardizing endpoint definitions led us to be much more deliberate about request and response contracts. Responses that were previously implicit or loosely defined are now explicitly documented in OpenAPI, which improved clarity, reduced accidental breaking changes, and made backend development more consistent and reviewable.

Stronger Reliability Between Backend and Frontend

Using generated API clients and types significantly improved reliability between backend and frontend by catching mismatches at compile time instead of runtime. While migrating from manually maintained types introduced some short-term friction and type errors, these issues consistently exposed real inconsistencies and resulted in more robust frontend implementations.

Better Visibility into API Usage and Optimization Opportunities

Typed API usage made it easier to see which endpoints are used by which screens and which response fields are actually required. Although we haven’t fully leveraged this yet, it creates a strong foundation for future optimizations such as reducing response sizes and aligning endpoints more closely with real usage patterns, bringing some GraphQL-like benefits to our REST setup.

Daily Developer Experience

From a frontend perspective, the developer experience has improved notably. Based on Jason’s experience, frontend developers now care less about plugging in API endpoints and can almost immediately start using them by simply wrapping them with React Query. This saves time and allows the team to focus on how data is consumed rather than on correctly fetching it. Additionally, pulling types directly from the OpenAPI Specification has elevated frontend type safety, as changes are now reflected immediately instead of requiring manual updates.

What’s Next

One natural next step is to package our generated API definitions as a versioned NPM package and publish a new release on every merge. This would clearly shift ownership of API contracts to the backend and allow frontend projects to consume a specific, immutable version of the API. The value of this approach increases as the number of backend and frontend services grows, especially in a multi-repo environment.

Another opportunity is reusing these API definitions across our other backend projects. Since some of our enterprise-facing services already depend on the main backend for certain operations, sharing a single, typed API contract would reduce duplication and make cross-service communication more explicit and reliable.

Longer term, we could move away from generating OpenAPI definitions via @nestjs/swagger annotations and instead generate OpenAPI JSON directly from TypeScript types. While this would create a cleaner, type-first contract model, it would require introducing additional tooling on the backend and refactoring all existing endpoints. Given the current cost and limited immediate benefit, this is not something we plan to pursue right now but it remains a potential direction if our architecture evolves further.

Why choose PostgreSQL GIN indexes full text search

Following is the image of GIN index data structure (https://pganalyze.com/blog/gin-index):

Choosing PostgreSQL GIN indexes for full-text search is mainly driven by ease of implementation and cost-effectiveness, as it provides indexed search speed directly within PostgreSQL without additional components. Since our codebase already runs on TypeORM with PostgreSQL, it only requires setting up the appropriate columns with a GIN index. This approach avoids the need to collect meaningful data, send it to third-party services, and then query those services via APIs or SDKs.

Given that we already have a PostgreSQL container with ample unused space, potential issues related to adding indices—such as increased storage—are minimal. PostgreSQL indices store extra data structures to enable faster data retrieval, which speeds up queries but also consumes additional storage. For example, GitLab encountered issues with large GIN indexes causing occasional slow updates due to the overhead of cleaning up the GIN pending list, sometimes resulting in multi-second stalls during operations (source). These issues arose from the heavy write workload on their large indices, requiring complex tuning and maintenance strategies to keep performance acceptable. However, this situation does not apply to us for the foreseeable future, as our database workload and size are much smaller, and we have sufficient resources to manage GIN index overhead without experiencing such bottlenecks.

By default, PostgreSQL uses B-tree indices, which employ a balanced tree structure where each index entry points to a single row. B-tree indices work best with straightforward data types like numbers, dates, and single values. However, when dealing with complex data types that hold multiple values in one column—such as arrays, JSON documents, or full-text search data—GIN indexes are the better option as they efficiently handle these multi-valued structures.

Using third-party search tools like Elasticsearch provides powerful, highly scalable full-text search capabilities with advanced features such as fuzzy matching, ranking algorithms, autocomplete, and complex aggregations. These tools are built specifically for search, offering fast and relevant results even on massive datasets. However, they bring overhead in the form of additional infrastructure to deploy and maintain, requiring data synchronization between your main database and the search cluster, which increases complexity and operational costs. Moreover, you must manage separate backups, security, and ensure consistency between data stores, which can complicate your system architecture compared to using built-in database search features.

So, we decided to give GIN a try.

Setting up GIN in TypeORM

By creating a generated column in the same table that combines text fields such as name and description into a single tsvector using PostgreSQL’s to_tsvector with a specified configuration (e.g., ‘english’), we can automatically update this column on each insert or update. This generated column can then be indexed with a GIN index, which is designed for sub-dividable data like full-text lexemes, enabling fast and efficient search queries without manually converting text to vectors on each request.

Key benefits include automatic updates of the full-text vector on data changes, speeding up search execution via the GIN index, and simplifying queries as they can directly search the indexed generated column rather than calling to_tsvector dynamically. While generated columns must reference only columns from the same table (thus requiring separate columns and indexes for related entities like design and template), this approach still avoids overhead of on-the-fly vector calculation and provides clear performance advantages.

Example from the Design entity with a generated searchVector column and corresponding GIN index demonstrates this setup:

@Index('idx_gin_design_search_vector', ['searchVector'])
@Column({
  type: 'tsvector',
  generatedType: 'STORED',
  asExpression: `to_tsvector('english', COALESCE(name, '') || ' ' || COALESCE(description, ''))`,
  nullable: false,
  select: false,
  insert: false,
  update: false
})
searchVector: string;

After generating a migration for the searchVector column, a couple of inaccuracies were spotted. TypeORM does not support creating GIN indexes natively, so we had to manually tweak the index creation SQL to include the GIN index type. Additionally, when creating a generated column, TypeORM inserts full details from the database into the typeorm_metadata table, including the database name. This means that if your local database name differs from the initial database used for migrations, TypeORM will regenerate all code for that generated column whenever new migrations are created.

Fixed migration look like this (USING GIN is a very important tweak, without it you will get B-Tree index created instead):

  public async up(queryRunner: QueryRunner): Promise<void> {
    await queryRunner.query(`
            ALTER TABLE "design"
            ADD "search_vector" tsvector GENERATED ALWAYS AS (
                    to_tsvector(
                        'english',
                        COALESCE(name, '') || ' ' || COALESCE(description, '')
                    )
                ) STORED NOT NULL
        `)
    await queryRunner.query(
      `
            INSERT INTO "typeorm_metadata"(
                    "database",
                    "schema",
                    "table",
                    "type",
                    "name",
                    "value"
                )
            VALUES ($1, $2, $3, $4, $5, $6)
        `,
      [
        'image_generator',
        'public',
        'design',
        'GENERATED_COLUMN',
        'search_vector',
        "to_tsvector('english', COALESCE(name, '') || ' ' || COALESCE(description, ''))"
      ]
    )

    await queryRunner.query(`
      CREATE INDEX "idx_gin_design_search_vector" 
      ON "design" USING GIN ("search_vector")
  `)
  }

The data stored into search_vector for design with name Heart Eyes Bunny and description: A cute pink bunny with heart-shaped eyes radiating love. Perfect for expressing affection in a fun way! looks like this: 'affect':18 'bunni':3,7 'cute':5 'express':17 'eye':2,12 'fun':21 'heart':1,10 'heart-shap':9 'love':14 'perfect':15 'pink':6 'radiat':13 'shape':11 'way':22.

The text represents a tsvector column value, which stores a processed, searchable version of a text document for full-text search. Each word (called a lexeme), like ‘affect’, ‘bunni’, or ‘cute’, is listed with numbers that indicate the positions where that word appears in the original text. This positional data helps PostgreSQL optimize phrase and proximity searches. The GIN index uses these lexemes and their positions to quickly find rows containing the searched words without scanning the entire text, making full-text search efficient and fast.

Finally, we update the API to handle search:

      const sanitizedSearch = sanitizeSearchString(options.search)
      const searchTerm = this.prepareSearchTerm(sanitizedSearch)
      const fullTextExpr = `
        "design"."search_vector" @@ to_tsquery(:query)
      `
      queryBuilder
        .addSelect(`similarity(design.name, :searchTerm)`, 'name_similarity')
        .addSelect(fullTextExpr, 'fulltext_match')
        .andWhere(`(${fullTextExpr} OR design.name ILIKE :searchPattern)`, {
          query: searchTerm,
          searchPattern: `%${sanitizedSearch}%`,
          searchTerm: sanitizedSearch
        })
        .orderBy('fulltext_match', 'DESC')
        .addOrderBy('name_similarity', 'DESC')
        .addOrderBy('design.createdAt', 'DESC')

This code performs a full-text search combined with a similarity ranking and fallback pattern match on the “design” entity. First, it sanitizes the search input and prepares it as a PostgreSQL tsquery term. Then, it constructs a query that checks if the search_vector (a precomputed tsvector column) matches the search term using full-text search operators. The query adds two computed columns: fulltext_match to indicate if the full-text search matched, and name_similarity to measure similarity between the search term and the design name. It filters results where either the full-text search matches or the name contains the search text pattern (ILIKE). Finally, it orders results by the full-text match flag first (descending), then by the similarity score, and lastly by creation date, ensuring the most relevant and recent records appear first.

The results of the API

We haven’t noticed any slowdown in our POST or PATCH APIs in practice—though theoretically they may take slightly longer, the difference is imperceptible. Meanwhile, our search performs quickly and reliably, consistently returning accurate results for both Products and Creators. The API response time typically stays within 200-250 ms, and with caching in place, it becomes even faster over time as more requests are served directly from cache, improving efficiency with continued use.

And SQL query always provides around 0.041s (0.001s fetch) for query, while executing this into the server that is in a different region:

SELECT
  design.*,
  similarity(design.name, 'dogs') AS name_similarity,
  (design.search_vector @@ to_tsquery('dogs')) AS fulltext_match
FROM
  design
WHERE
  (design.search_vector @@ to_tsquery('dogs') OR design.name ILIKE '%dogs%')
ORDER BY
  fulltext_match DESC,
  name_similarity DESC,
  design.created_at desc
limit 5;

The query plan shows that the GIN index on the search_vector column is effectively utilized to accelerate full-text search. The plan includes a Bitmap Index Scan on the GIN index followed by a Bitmap Heap Scan on the design table, filtering rows that match the full-text condition or the trigram index on the name column. The sorting is performed with a top-N heapsort based on the full-text match, similarity score, and creation date. The entire query runs efficiently with an execution time of just over 2 milliseconds:

Limit  (cost=341.80..341.81 rows=5 width=551) (actual time=2.305..2.307 rows=5 loops=1)
  ->  Sort  (cost=341.80..342.15 rows=139 width=551) (actual time=2.305..2.306 rows=5 loops=1)
        Sort Key: ((search_vector @@ to_tsquery('dogs'::text))) DESC, (similarity((name)::text, 'dogs'::text)) DESC, created_at DESC
        Sort Method: top-N heapsort  Memory: 29kB
        ->  Bitmap Heap Scan on design  (cost=119.06..339.49 rows=139 width=551) (actual time=1.171..2.023 rows=135 loops=1)
              Recheck Cond: ((search_vector @@ to_tsquery('dogs'::text)) OR ((name)::text ~~* '%dogs%'::text))
              Heap Blocks: exact=108
              ->  BitmapOr  (cost=119.06..119.06 rows=139 width=0) (actual time=1.132..1.133 rows=0 loops=1)
                    ->  Bitmap Index Scan on idx_gin_design_search_vector  (cost=0.00..24.38 rows=138 width=0) (actual time=0.371..0.372 rows=135 loops=1)
                          Index Cond: (search_vector @@ to_tsquery('dogs'::text))
                    ->  Bitmap Index Scan on trgm_idx_name  (cost=0.00..94.61 rows=1 width=0) (actual time=0.760..0.760 rows=8 loops=1)
                          Index Cond: ((name)::text ~~* '%dogs%'::text)
Planning Time: 0.406 ms
Execution Time: 2.355 ms

This demonstrates how GIN indexes combined with similarity and trigram indexes can deliver fast, accurate full-text search results with efficient query execution.

To Sum Up

To sum up, at Ablo AI, we initially used PostgreSQL’s simple LIKE-based search, which worked only for small datasets. As we scaled and added features, this approach became too slow and caused high API latency. Instead of adopting third-party search tools like Elasticsearch, we decided to maximize PostgreSQL’s native capabilities by using GIN indexes for full-text search. This approach fits well with our existing TypeORM setup, requires less infrastructure overhead, and delivers fast, automated search vector updates and queries. We created generated columns combining text fields into tsvector columns that are automatically updated and indexed with GIN. While we had to manually adjust SQL to correctly create GIN indexes due to TypeORM limitations, the benefits are clear: fast, consistent search performance with minimal maintenance complexity. The tsvector columns store tokenized words with positions, allowing GIN to efficiently locate matches. Our API combines full-text search with similarity ranking and pattern matching, delivering results within 200-250 ms, with query plans confirming the effective use of GIN and trigram indexes in just a few milliseconds. This demonstrates how harnessing PostgreSQL’s full-text search capabilities with GIN indexes can provide scalable, high-performance search without the complexity of external search services.

Sources

• https://www.postgresql.org/docs/current/gin.html [2025-10-09]

• https://pganalyze.com/blog/gin-index [2025-10-09]

• https://gitlab.com/gitlab-com/gl-infra/production/-/issues/4725#note_596146675 [2025-10-09]

As your app grows, features, utilities, third-party packages pile up and the amount of JavaScript you ship grows with them. That extra JS has to be downloaded, parsed, and executed before users can fully interact (and in many SPAs, before the initial screen hydrates). So, the more you ship, the slower the startup? Pretty much yes, unless you do some code splitting.

Think of code splitting as slicing your app into smaller bundles that the browser loads only when they’re needed (for the current route or interaction). This optimization shortens the initial load and directly improves metrics measured by tools like Lighthouse, Google’s automated tool for auditing web performance and accessibility. Strong Lighthouse scores often reflect healthy Core Web Vitals, metrics like Largest Contentful Paint (LCP) and Cumulative Layout Shift (CLS) that affect both user experience and search ranking. You can read more about code splitting in the React docs.

2. React-based code splitting

a. Route-based splitting

This is the classic move: split by page or route. Each route’s UI becomes its own bundle, loaded only when the user navigates there. It’s clean because routes are natural boundaries in your app. This is often the first cut people make.

// Assume a router setup with React Router
const Home = React.lazy(() => import('./pages/Home'));
const Profile = React.lazy(() => import('./pages/Profile'));

function AppRouter() {
  return (
    <Suspense fallback={<div>Loading…</div>}>
      <Routes>
        <Route path="/" element={<Home />} />
        <Route path="/profile" element={<Profile />} />
      </Routes>
    </Suspense>
  );
}

b. Component-level splitting

Within a route, you may have heavy components (charts, editors, modals, maps). Use lazy loading on those so you avoid shipping them by default. Even if the user never opens a modal or expands the editor, they won’t incur that cost.

function Dashboard() {
  const HeavyChart = React.lazy(() => import('./charts/HeavyChart'));
  return (
    <div>
      <h2>Your activity</h2>
      <Suspense fallback={<div>Chart loading…</div>}>
        <HeavyChart />
      </Suspense>
    </div>
  );
}

c. Library splitting

You can extract large third-party libraries (Stripe, DnD, fabric, data viz libs) into their own chunks. They’re loaded only when features requiring them activate. This lets your core app stay lean, while these “big rocks” sit dormant until needed.

3. Route Based Splitting and Vite SSR are not good friends

We built our stack on Vite’s SSR, expecting route-based splitting to mostly work out of the box. Instead, we ended up staring at broken routes, weird freezes, and more console errors than confidence. The problems we encountered boiled down to three systemic pains:

• Hydration mismatches: the HTML sent by our server would sometimes diverge from what React expected on the client, triggering errors like “Hydration failed”. In SSR environments, mismatches aren’t rare. To tame this, we looked at libraries that advertise smoother SSR + lazy boundary integration. Loadable Components, for instance, presents itself as a better fit for SSR than React.lazy, offering tooling to help align server and client rendering.

• Tooling friction with SSR + lazy libraries: We experiment with Loadable Components, but moved away since this is not compatible with Vite. Then, we tried also Vite preload, but wiring it into our stack wasn’t as smooth as the docs suggest. Parts of our app became unresponsive, and we had to build custom logic to patch over some of those issues. What stabilized eventually cracked again when authentication flows were involved.

• Auth logic: Even when chunking worked, some user flows, especially around login, started failing. For example, after authentication the app sometimes treated the user as still unauthenticated.

Together, these pains taught us that “route splitting under ViteSSR” is far from a lightweight refactor or a quick win. It demands deep orchestration between routing, lazy loading, manifest wiring, and authentication. Trying to build it from scratch felt a lot like rewriting your own framework. So we decided to look elsewhere for performance gains.

4. What we shipped: Good old library splitting

We took a pragmatic approach, not trying to split everything, but isolating what hurt us most. The ultimate goal was to reduce our main bundle size and shave milliseconds off startup. That’s why we pivoted toward library splitting instead of wresting with full route-based code splitting under SSR.

const MODULES_FOR_SEPARATE_CHUNKS = [
  '@stripe/stripe-js',
  '@stripe/react-stripe-js',
  ... // rest of heavy libraries
];

export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        manualChunks(id) {
          const ROLLUP_COMMON_MODULES = [
            'vite/preload-helper',
            'vite/modulepreload-polyfill',
            'vite/dynamic-import-helper',
            'commonjsHelpers',
            'commonjs-dynamic-modules',
            '__vite-browser-external',
          ];

          if (
            id.includes('node_modules') &&
            MODULES_FOR_SEPARATE_CHUNKS.find((module) => id.includes(module))
          ) {
            return id.toString().split('node_modules/')[1].split('/')[0].toString();
          }

          if (
            id.includes('node_modules') ||
            ROLLUP_COMMON_MODULES.some((commonModule) => id.includes(commonModule))
          ) {
            return 'vendor';
          }
        },
      },
    },
  },
  ...//rest of config
})

In our vite.config.js, we declared a MODULES_FOR_SEPARATE_CHUNKS array that lists heavyweight dependencies we want carved out of the main bundle. In the manualChunks(id) function, we check if the module path (id) comes from node_modules and matches one of those listed modules. If so, we return the module’s name so Vite/Rollup builds it into its own chunk. For anything else in node_modules, we funnel them into a shared vendor chunk. The result: heavy libraries live in isolated bundles only fetched when needed, while the core of our app stays lean.

A few caveats worth knowing: Vite/Rollup’s manual chunking isn’t foolproof. Issues like chunks loading earlier than expected or duplication sometimes appear in real-world setups Here is a link to the issue in Github: https://github.com/vitejs/vite/issues/5189

5. Faster load times

After deploying our optimizations indeed our app load time felt significantly faster. We started seeing Lighthouse scores pop into the 90s on several pages. That kind of result signals you’re in the “green zone” for performance (Lighthouse marks 90+ as “good”). These results confirmed that our surgical splitting, deferring of heavy scripts, and chunking strategy weren’t just theoretical—they moved practical metrics.

To be precise, the scores referenced here were measured on October 7, 2025, giving us a date-stamped benchmark for comparison.

6. What’s Next?

We started off looking for a quick win, route splitting, turn the lever, get performance. But ViteSSR & route code splitting turned out to be a beast: hydration mismatches, odd auth bugs, and tooling friction were true boss fights. By focusing on surgical cuts like deferring third-party scripts, isolating heavy libs, and letting the main bundle stay lean we managed to achieve really nice results.

Of course, optimizations never really stop. We can continue pushing: splitting out more chunks, preloading fonts only in the editor, asynchronously loading those small CSS files only when needed, tightening cache lifetimes, and squashing layout shifts. And if those efforts don’t feel enough, migrating to a purpose-built framework remains on the table as a fallback, though not our only path forward.

At Space Runners, we’ve embraced comprehensive end-to-end testing as a pillar of our engineering culture. Our E2E test suite covers over 90% of the backend logic, helping us catch regressions early, ensure contract stability, and build with confidence. But as our systems and team scaled, so did the need for faster, more efficient testing infrastructure without compromising on coverage or reliability.

Why We Considered a Change

While our test suite was comprehensive, it came at a cost: our CI pipeline was taking nearly 15 minutes to complete. This delay significantly slowed down our development feedback loop, especially painful during hotfixes or urgent releases. We found ourselves either waiting unproductively for builds to finish or, worse, skipping tests to save time. Neither option was sustainable.

After evaluating alternatives, we decided to migrate our backend tests from Jest to Vitest. The transition was appealing for several reasons: Vitest shares a nearly identical API with Jest, making it easy to swap out without massive refactoring. It's also built on top of the Vite ecosystem, which continues to gain traction in the frontend and backend communities alike. With strong community adoption, active development, and detailed migration guides, Vitest provided a smooth and well supported path forward.

Configuring Vitest for our Stack

Getting Vitest up and running in our backend wasn’t entirely plug-and-play, but the process was manageable thanks to our existing setup. Since we were already running Jest with SWC, we had most of the necessary infrastructure in place. The primary additions were a new vitest.config.ts file and an update to our tsconfig.json to include Vitest’s global types via "types": ["vitest/globals"].

{
  "compilerOptions": {
    ...
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true,
    ...
    "types": ["vitest/globals"]
  }
}

By default, Vitest uses ESBuild to transform code. However, because our NestJS + TypeORM backend relies heavily on metadata (especially for decorators), we needed a transformer that supports it properly. ESBuild lacks full metadata support, so we opted to use SWC instead. The unplugin-swc package made this integration straightforward, allowing us to plug SWC into Vitest without needing to change our existing build pipeline.

// vitest.config.ts
import swc from 'unplugin-swc'
import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    globals: true,
    environment: 'node',
    pool: 'threads',
    poolOptions: {
      threads: {
        singleThread: true
      }
    },
  },
  plugins: [swc.vite()]
})

To ensure correct metadata handling, our .swcrc configuration includes "legacyDecorator": true and "decoratorMetadata": true. These flags are essential in projects that use TypeORM entities and decorators, like ours.

// .swcrc
{
  "$schema": "https://swc.rs/schema.json",
  "sourceMaps": true,
  "jsc": {
    "parser": {
      "syntax": "typescript",
      "decorators": true,
      "dynamicImport": true
    },
    "transform": {
      "legacyDecorator": true,
      "decoratorMetadata": true
    },
  },
}

Lastly, due to some setup constraints with our current test structure, we opted to run tests in a single-threaded pool. While Vitest supports parallel test execution, we deferred that optimization to avoid introducing flaky test behavior before stabilizing the new setup.

Challenges in the Migration

At first glance, migrating from Jest to Vitest looked relatively simple. Both frameworks share nearly identical testing APIs. However, once we began running tests in our actual backend environment, deeper issues started to surface. The core challenges came down to the specifics of how Vitest handles module resolution, metadata, and ESM mocking.

1. TypeORM Compatibility

Our backend is built on NestJS and TypeORM, which heavily depend on decorators and runtime metadata. This became one of the more stubborn issues in the migration. When configuring TypeORM in tests, our original approach was to pass file path patterns (e.g., **/*.entity.ts) to define the entity list. However, Vitest’s transformation layer struggled to preserve metadata information when resolving those files dynamically.

To resolve this, we switched to importing every entity manually and passing them as an array to the TypeORM configuration. While this is slightly more verbose and rigid, it ensured that decorator metadata was preserved and the ORM could correctly reflect on the entities. We also tried referencing compiled JavaScript paths, but this too resulted in missing metadata issues.

One caveat with this approach is that every entity must be explicitly included. Missing even one results in confusing errors or unexpected runtime failures. We’ve since made this part of our setup more maintainable by centralizing entity imports in a shared module.

2. Mocking ESM Modules

Another tricky area was mocking third-party ESM modules. In our case, Vitest wasn’t reliably able to mock certain ESM-only packages, like potrace. Direct mocks would either fail silently or break at runtime.

Our workaround was to introduce internal wrapper functions around these modules. Instead of importing potrace directly in our tests or application logic, we created utility helpers that internally used potrace, and then mocked those helpers in tests. This added a small layer of indirection, but it allowed us to keep tests deterministic and compatible with Vitest’s mocking system. Thankfully, the number of affected modules was small, and we were able to refactor them without much disruption.

Results of the Migration

Despite some initial hiccups during the migration, the results have been undeniably worth it. Our CI runtime dropped from 15 minutes to just 4, and local test runs now complete in around one minute. This dramatic improvement in speed has made testing a frictionless part of development. We are no longer hesitant to run the full test suite locally, and urgent deployments or hotfixes are no longer bottlenecked by slow CI feedback.

Another key benefit was test monitoring support. Vitest integrates smoothly with tools that allow us to track test performance over time and gather insights on memory leaks and coverage changes. This gives us visibility we previously lacked, helping us proactively improve test quality.

What’s Next?

The migration from Jest to Vitest was absolutely worth it. Although, there were technical hurdles mainly around TypeORM and ESBuild quirks the performance gains and improved developer experience have made a measurable difference. Our tests are faster, lighter, and better integrated with modern tooling.

We’re now exploring parallel test execution, which could further reduce CI times. However, running E2E tests in parallel introduces complexity, particularly around database state isolation. Solving these challenges is our next focus as we continue to scale our infrastructure.

Server side rendering (SSR) is a technique where a page with all of its content is generated on the server and sent to the browser fully populated. This technique helps with SEO and makes the site feel snappier on initial load, although it adds implementation complexity. In the old days of the web everything was server side generated, but then single page apps (SPAs) were introduced and they offered a much better user experience. These days modern frameworks based on React use a hybrid approach which works like this:

1. A page is generated on the server, populated with data and sent to the browser

2. On the browser side the page is visible immediately and then the client side script adds interactivity and event handlers

3. As you navigate through the app with links you get the interactivity of a SPA

4. Internal pages such as dashboards and editors where SEO doesn't matter are just regular SPAs

This article will focus on a high-level overview on how to take a SPA built with the popular build tool Vite and add SSR to it using native Vite tools, without committing to a framework. If you browse online through Reddit and various forums, you’ll find that many teams are asking questions like: “How do I build the home page with SSR and then the rest of the app with Vite”. There aren’t many resources with definitive answers except that it’s possible. This article aims to shed some light on this entire process and how it worked out for us.

Motivation for SSR in Ablo

Ablo offers a comprehensive editor tool where artists create beautiful designs, but it also offers a storefront where consumers can buy these designs. The latter has to be indexable by Google and easily discoverable on the web because we want to maximize the traffic we get on these pages. Maximizing traffic on every e-commerce related page means more people going into the sales funnel and ultimately more sales. These are pages used for marketing such as the home page or the page with a list of products or product details. If we only had these kind of pages, we would be better served with a framework such as NextJS or Remix.

However, the bulk of our app is the entire ecosystem around the editor and all the admin pages focused around publishing and managing designs. At the time of this writing we’re about to build a huge creator hub module with tools which artists will use to maximize their earnings. All of these pages are behind a login and use client-side libraries such as fabric.js or later on charting libraries for dashboards. They aren’t indexed by Google so they don’t need SEO considerations and SSR support. Since its inception Ablo has been a pure SPA centered around design tools and AI image generation. The merch shop and e-commerce aspect came later. Like many SPAs out there, Ablo uses Vite as its build tool because of unparalleled simplicity, flexibility, and speed of development. Unlike frameworks it doesn’t force you into a specific paradigm. It just does its job and gets out of the way.

Like many apps, when Ablo recently got the requirement to have a subset of its pages rendered on the server, we evaluated different solutions. Thankfully, Vite has SSR support and although it’s not a fully fledged SSR framework, it provides tools to effectively and easily build an SSR solution while maintaining all the benefits previously mentioned. For us this meant that we got to keep our existing workflows and implement SSR on a few of our pages with minimal effort.

A worthy mention is vite-ssr, a framework for SSR with Vite. Their site has a comprehensive comparison with popular frameworks and it makes a great sales pitch on all of its benefits. However, we decided not to go with this solution because it’s paid and we saw a clear path on how to achieve our goals with a custom solution.

Measuring the results

Our end goal with SSR was to improve page speed load and ultimately SEO, because the latter depends on the former. There are many free and paid tools online which measure page speed load, but the first step is to start with Google’s Lighthouse. It can be ran from Chrome DevTools to get fast feedback during development on how different approaches affect performance. Here’s our score for Ablo’s home page on a pure SPA without SSR:

As you can see, it’s not very good. This was our starting point. After we implemented SSR and also added a couple of optimizations on how we store and serve images, it’s much better:

Getting started

Vite has good documentation on how to work with SSR, but they go into too much details on some things so you miss out on what’s important. We’ll present a bare bones version that’s already in production in our case, works well, and took a couple of days to implement. If we assume that you already have a Vite app, the first thing is to install Express: npm i express because you’ll need a server to serve the pre-generated static pages. Here’s the basic idea of SSR with Vite:

1. In dev mode you use Vite’s Hot Module Reload (HMR) server as Express middleware. This allows for instant feedback in the browser as you make changes in the code. That’s a feature that everyone got used to when working with Vite and you can still use it.

2. In production the Vite app is built into a dist folder as usual, without SSR. However, in this case the Express server reads this HTML and pre-renders data before sending it to the client.

3. There are two entry points to the app: entry-client.tsx and entry-server.tsx . For existing Vite apps the client entry point is the same main file which they currently use. The server entry point has all the pre-rendering logic and a static router for routes with SSR.

4. In production the client entry point is built into the client bundle as described in point 2, and the server side is also built into its own distribution folder.

The entry point to the server (Express) side is the server.js file. It’s a simple file which embeds the logic described above.

import express from 'express';

import fs from 'node:fs/promises';

const base = process.env.BASE || '/';

const isProduction = process.env.NODE_ENV === 'production';

// Cached production assets
const templateHtml = isProduction ? await fs.readFile('./dist/client/index.html', 'utf-8') : '';

// Create http server
const app = express();

// Add Vite or respective production middlewares
/** @type {import('vite').ViteDevServer | undefined} */
let vite;

if (!isProduction) {
  // In development we use the good old Vite HMR server, but as an Express middleware here
  const { createServer } = await import('vite');

  vite = await createServer({
    server: { middlewareMode: true },
    appType: 'custom',
    base,
  });
  app.use(vite.middlewares);
} else {
  const compression = (await import('compression')).default;
  const sirv = (await import('sirv')).default;
  app.use(compression());
  app.use(base, sirv('./dist/client', { extensions: [] }));
}

// This is a catch all route used as en entry point to render the initial page
app.use('*all', async (req, res, next) => {
  const url = req.originalUrl;

  try {
    let template;
    /** @type {import('./src/entry-server.js').render} */
    let render;

    if (!isProduction) {
      template = await fs.readFile('./index.html', 'utf-8');
      template = await vite.transformIndexHtml(url, template);
      // The entry point to SSR for the initial load in dev mode
      render = (await vite.ssrLoadModule('/src/entry-server.tsx')).render;
    } else {
      // In production the entry-server file is built into a distribution folder
      template = templateHtml;
      render = (await import('./dist/server/entry-server.js')).render;
    }

    // The entry-server file always has to implement a "render" method which is used to generate
    // the HTML that will be returned to the browser on initial load
    const {
      head,
      html: appHtml,
      dehydratedState: initialData,
    } = await render({
      path: url.split('?')[0],
      userAgent: req.headers['user-agent'],
    });

    // The Helmet part is to support meta tags, which is a topic for a future article
    const html = template
      .replace(`<!--helmet-outlet-->`, () => head)
      // The index html has a comment area which is replaced with the actual HTML on initial load
      .replace(`<!--ssr-outlet-->`, () => appHtml)
      // This part is to inject preloaded data into the page immediately, without fetching it on
      // client side. For example, you preload products on the server and inject the entire 
      // resulting JSON into the HTML which is then picked up by the client side code
      .replace(
        '<!--dehydrated-state-->',
        `<script>window.__REACT_QUERY_STATE__ = ${JSON.stringify(initialData)}</script>`
      );

    // Send the rendered HTML back.
    res.status(200).set({ 'Content-Type': 'text/html' }).end(html);
  } catch (e) {
    // If an error is caught, let Vite fix the stack trace so it maps back
    // to your actual source code.
    console.log('Err', e);
    vite.ssrFixStacktrace(e);
    next(e);
  }
});

app.listen(5173);

There are two important parts in the code above:

1. <!--ssr-outlet--> - this is a comment in the index.html which tells the server where to inject the pre-rendered HTML. This is a fully populated document structure which you can see coming back from the server if you filter by “Doc” in Chrome DevTools:

2. <!--dehydrated-state--> - this comment marks the area where the server will inject data pre-loaded on the server. For example, on our Merch Shop page above we have a list of brands. In an SPA, the page would load these brands from the server on mount and show a loading spinner. With SSR we preload the brands on the server, but we have to inject them somehow into the client side code. We do that by serializing it and replacing this comment with the serialized state. On the client, a library like `react-query` picks up this state and just renders the data. This is a topic for the next installment of this article series.

Server entry

// src/entry-server.tsx
import { renderToString } from 'react-dom/server';
import { ChakraProvider } from '@chakra-ui/react';
import { dehydrate, QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { Route, StaticRouter } from 'react-router-dom';

import theme from '@/theme';

import HomeSignedIn from './views/home/HomeSignedIn';
import SelectTemplatePage from './views/template/SelectTemplatePage';
import { getCategories } from './api/templates';

import './index.css';

import ProductsPageAuthenticated from './views/products/ProductsPageAuthenticated';

import ProductDetailsPage from './views/product/ProductDetailsPage';

import { Helmet } from 'react-helmet';
import CreatorHubSignedIn from './views/creator-hub/CreatorHubSignedIn';

interface IRenderProps {
  path: string;
}

export async function render({ path }: IRenderProps) {
  const queryClient = new QueryClient({
    defaultOptions: {
      queries: {
        staleTime: 1000 * 60 * 5, // 5 minutes
      },
    },
  });

  await queryClient.prefetchQuery(['templates', 'categories'], () => getCategories());

  const html = renderToString(
    <ChakraProvider theme={theme}>
      <QueryClientProvider client={queryClient}>
        <StaticRouter location={path}>
          <Route exact path="/" render={() => <HomeSignedIn />}></Route>
          <Route
            exact
            path="/shop/category/:categorySlug"
            render={() => <ProductsPageAuthenticated />}
          ></Route>
          <Route
            path="/shop/community/:brandIdOrSlug/:categorySlug"
            render={() => <ProductsPageAuthenticated />}
          ></Route>
          <Route path="/shop/:idOrSlug" render={() => <ProductDetailsPage />}></Route>
          <Route path="/design-studio" render={() => <SelectTemplatePage />}></Route>
          <Route path="/creator-hub" render={() => <CreatorHubSignedIn />}></Route>
        </StaticRouter>
      </QueryClientProvider>
    </ChakraProvider>
  );

  const helmet = Helmet.renderStatic();

  const head = `
      ${helmet.title.toString()}
            ${helmet.meta.toString()}
            ${helmet.link.toString()}
            `;

  const dehydratedState = dehydrate(queryClient);

  return {
    head,
    html,
    dehydratedState,
  };
}

The server entry file looks like a normal entry file to a React app on the client side, with a top level router. What’s different is that it uses the renderToString method to turn the React component tree to raw HTML. We use Chakra UI as our styling library and you can see how it can seamlessly be used in SSR. Another thing to notice here is how we pre-hydrate the react-query query client. We do the same API calls as we would on the client side here on the server and then store them into react-query ‘s internal state. At the end we pull all of the query client’s internal state to dehydratedState which is then used in entry-client as you’ll see in the next section.

Client entry

import React from 'react';
import { hydrateRoot } from 'react-dom/client';

import { isAxiosError } from 'axios';

import { BrowserRouter, Route, Switch } from 'react-router-dom';

import { IntercomProvider } from 'react-use-intercom';

import * as Sentry from '@sentry/react';

import AdminDashboard from '@/layouts/admin';
import Auth from '@/layouts/auth';
import { ChakraProvider } from '@chakra-ui/react';
import ResetPasswordPage from '@/views/auth/reset-password';
import theme from '@/theme';

import { QueryClient, QueryClientProvider, DehydratedState, Hydrate } from '@tanstack/react-query';
import { GoogleOAuthProvider } from '@react-oauth/google';

import Config from './config';
import { PageTracker } from './analytics/PageTracker';

import './index.css';
import { Helmet } from 'react-helmet';
import DEFAULT_TOAST_OPTIONS from './theme/toast';

declare global {
  interface Window {
    __REACT_QUERY_STATE__: DehydratedState;
  }
}

const { ENVIRONMENT, GOOGLE_CLIENT_ID, INTERCOM_APP_ID, SENTRY_DSN } = Config;

const container = document.getElementById('app');

if (import.meta.env.PROD) {
  Sentry.init({
    dsn: SENTRY_DSN,
    environment: ENVIRONMENT,
    integrations: [new Sentry.BrowserTracing(), new Sentry.Replay()],
    tracesSampleRate: 0,
    // Session Replay
    replaysSessionSampleRate: 0.1, // This sets the sample rate at 10%. You may want to change it to 100% while in development and then sample at a lower rate in production.
    replaysOnErrorSampleRate: 1.0, // If you're not already sampling the entire session, change the sample rate to 100% when sampling sessions where errors occur.
  });
}

const MAX_RETRIES = 6;
const HTTP_STATUS_TO_NOT_RETRY = [400, 401, 403, 404, 409];

const dehydratedState = window.__REACT_QUERY_STATE__;

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      refetchOnWindowFocus: false,
      retry: (failureCount, error) => {
        if (failureCount > MAX_RETRIES) {
          return false;
        }

        if (isAxiosError(error) && HTTP_STATUS_TO_NOT_RETRY.includes(error.response?.status ?? 0)) {
          console.log(`Aborting retry due to ${error.response?.status} status`);
          return false;
        }

        return true;
      },
    },
  },
});

hydrateRoot(
  container,
  <React.StrictMode>
    <IntercomProvider appId={INTERCOM_APP_ID}>
      <GoogleOAuthProvider clientId={GOOGLE_CLIENT_ID}>
        <QueryClientProvider client={queryClient}>
          <Hydrate state={dehydratedState}>
            <ChakraProvider theme={theme} toastOptions={{ defaultOptions: DEFAULT_TOAST_OPTIONS }}>
              <BrowserRouter>
                <PageTracker />
                <Helmet>
                  {ENVIRONMENT !== 'production' ? <meta content="noindex" name="robots" /> : null}
                  <title>ABLO – AI‑Powered Fashion & Custom Merch</title>
                  <meta
                    name="description"
                    content="Create premium fashion with AI. Collaborate with iconic brands & design merch in minutes. Shop unique pieces from the creators you love."
                  />
                </Helmet>
                <Switch>
                  <Route path={`/auth`} component={Auth} />
                  <Route path={`/reset-password`} component={ResetPasswordPage} />
                  <Route path={`/`} component={AdminDashboard} />
                </Switch>
              </BrowserRouter>
            </ChakraProvider>
          </Hydrate>
        </QueryClientProvider>
      </GoogleOAuthProvider>
    </IntercomProvider>
  </React.StrictMode>
);

The client entry file is just a React app, but as described before, you’ll notice how we load the server query client’s state into the client side query client. On the server we preloaded all the data and stored it into a string. We loaded this string into the query client on the client side. This will be explained in more detail in a future article.

New commands in package.json

Here’s the end state of our scripts in package.json:

 "scripts": {
    "dev": "vite",
    "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 20",
    "typecheck": "tsc --noEmit",
    "build:library": "tsc && vite build --config vite-lib.config.ts",
    "build:fabric": "cd node_modules/fabric && npm run build_with_gestures",
    "preview": "vite preview",
    "build:client": "vite build --outDir dist/client",
    "build:server": "vite build --ssr src/entry-server.tsx --outDir dist/server",
    "build:ssr": "npm run build:client && npm run build:server",
    "build": "vite build",
    "start": "node server.js",
    "start:prod": "NODE_ENV=production npm run start"
  },

When in development and you don’t need to test or work with SSR you use npm run dev . When you need to work with SSR in development you use npm run start . For production you first build the app with npm run build:ssr and then you run npm run start:prod

Conclusion

This should explain basic strategies around implementing SSR with Vite and get you running with your own implementation. Future installments of this article series will go deeper into specific concepts and details such as working with data.

v1.3

Overview

To build a well-designed, efficiently functioning engineering team, we should agree on how we work with each other. These principles will guide us in day to day decision making and ensure we know what to expect from each other. This is a living document and will evolve as the team evolves and with everybody's input.

Workflow

Standup / Daily Sync

Asynchronous Written Standup

You should post daily whenever you start work in the Slack #standup channel a detailed status update that includes:

1. What you accomplished previously / yesterday

2. What you plan on accomplishing today / next

   1. Indicate your top focus by putting a (TF) next to the item that's most important today

3. Any blockers, dependencies, or obstacles in your way

   1. Call out any team members you're depending on

   2. Help team resolve blockers asap!

Synchronous Video Standup

For our synchronous video standup, you should focus on just 2 things:

1. The most important thing you want to accomplish today (TF)

2. Any obstacles in your way to accomplish that thing

If anybody has any blockers, the team should rally to remove those blockers and get everybody productive asap.

Sprintly Recurring Events & Ceremonies

First Monday

• Sprint kick off / planning meeting - 1h

Finalize previous sprint and review tasks to be delivered in current sprint. Ensure estimates are accurate and tasks are well-defined. Commit to delivery.

• Push to Production - 1h

As long as no critical or high priority bugs exist. If P0 or P1 bugs exists, need to fix asap before we can release to production.

First Friday

• Mid-Sprint Checkin - 30m

Check-in during standup to see if we're on track for the week to deliver all our commitments for the most important epics on the roadmap. If it looks like anything will slip, see if we can potentially shuffle around any work.

2nd Thursday

• Demo Prep

Take some time to prepare for your demo so that you can successfully show off what you've accomplished in the sprint.

• Demo

Demo the most impactful things you've accomplished in the sprint. Limit it to 5m and really highlight the most impactful things. You don't need to demo every single thing you did, especially not bug fixes (unless they're very impactful).

• EOD code freeze

Wrap up an PRs you're working, help other devs get their code merged in, and start testing and preparing your demo.

2nd Friday

• Internal Testing

We should focus on testing the changes, fixes, and updates we just implemented in the last sprint. We should ensure the team is equally split between testing mobile, desktop, and BE. We should test on staging builds.

• Next Sprint Proposal and Estimation

Karim will work with Drew on the roadmap and propose tasks for next sprint and team should give their own estimates. All tasks should be reviewed and estimates completed before the sprint kickoff session on Monday.

Planning

In order to work effectively, we must ensure that the work we plan to do in any given sprint is clearly-defined and actionable. That means that before we commit to doing some work in a sprint, that we've fully digested the task and asked any clarifying questions if we need to do. It also means that we've called out any dependencies and worked with product or engineering leadership to ensure those dependencies are prioritized and actionable by the right person or group.

We should NOT commit to doing work in a sprint if it's not actionable

(Unless it's an emergency and/or it's super important that the work is delivered in this sprint. If we have dependencies in a sprint that need research to properly estimate, we can adjust sprint commitments after necessary research is done.)

Tech-Specs

Any non-trivial piece of technical work, and especially for any new APIs, or updates to APIs, we should write a tech spec to align on how we're going to do the work.

This will ensure everybody is happy, or at least on board, with the implementation details and will help to reduce technical debt going forward. As with everything we do as a startup, there needs to be a balance between doing things the safest / most optimal / most scalable / most correct way vs moving fast. We can talk about those trade-offs in the tech spec and associated meetings (if necessary).

Individual Task Workflow

1. Move your highest priority task from 'TO DO' to 'IN PROGRESS'

Humans are by nature single threaded - You can only do one thing at once, so ensure you only have one task IN PROGRESS at any given time_. Anybody in the company should be able to look at our sprint board and know exactly what any of us are working on this very instant._

2. For any coding task, no matter how small, create a branch for your work using the ClickUp UI.

3. We should shoot for smaller, more focused PRs.

PRs should accomplish a single thing. Smaller PRs are easier to digest, test, and review than large PRs. This ensures quality and alignment. Totally fine to have multiple PRs per ticket - not totally fine to have multiple tickets per PR.

4. Commit early and often.

Commits should be for small subtasks and the message should be a short description of what you did._

5. When a coding task is done, create a PR

ClickUp should automatically move the task to REVIEW_. When the PR is merged, ClickUp should automatically move the task to_ STAGING_._

6. Explicitly request review from at least one contributor to the repo so they get a notification about it

7. If changes are requested, as soon as you make changes and are ready for another review, click the button in Github to re-request review so the reviewer is notified.

Communication

Since we are a globally distributed team, we should default to asynchronous, written communication via Slack. If there are more than a few back and forths in Slack, then it's a sign that you should handle the conversation synchronously - either by huddling immediately or scheduling a future meeting if necessary. If you need to schedule a meeting, just fine time on people's calendar this is free. We should expect that people's calendars are up to date and reflect their availability.

In addition, since you can't always count on a quick response and back and forth with someone on Slack, we must ensure our communication is concise, but complete. Your written communication should leave no ambiguity to the reader. You should always err on the side of over-communication if you're ever unsure.

Cave / Focus Time

Engineering work requires deep focus. You can and should plan to eliminate distractions from your personal life and your work life so that you can do your best work.

You can add focus time to your calendar to ensure you aren't disrupted by meetings. You can also set your Slack status to 'Cave Time' to indicate to coworkers that they shouldn't disturb you unless it's an emergency.

Collaboration

We value collaboration and mentorship, and recognize that it's not a one way street. Of course, more junior people can learn from more senior people, but more senior people can also learn from junior people.

Availability

In order to effectively collaborate, we must be available to each other for synchronous work. Regardless of your timezone, you should be available for meetings, pair programming, and other synchronous things from at least the hours of:

• 0700 to 1000 PT

• 1000 to 1300 ET

• 1200 - 1700 UTC

• 1400 - 1900 CEST

Solving Issues

If you're ever stuck on an issue for more than 30 minutes, that's a good sign that you should reach out to the team for help. Likely, there's someone on the team who has seen your issue before and can save the team a lot of time.

Pair Programming

We value the practice of pair programming and aim to do it at least once per week with another developer on the team. We recommend the driver / navigator methodology. In this method, the driver is the one who is controlling the keyboard and mouse and the navigator is the one who tells the driver what to do, like you're driving a rally car together. If the driver disagrees, then the driver and the navigator should discuss the best implementation. This method is advantageous because it ensures the one who is not typing stays engaged and forces two way learning.

For most of us engineers, our natural inclination is to hunker down and solve problems by ourself. Solving problems together can be rewarding and fun! Make an effort to reach out to your coworkers and suggest a pair programming session!

Branching

For every piece of work we do, we branch. For consistency and for the tight integration with Github, we use the branch name provided by ClickUp:

Tip: branch names are not editable, but you can temporarily change the ticket name to something more git-readable and lowercase before creating the branch

Using the branch name from ClickUp will ensure that:

1. ClickUp automatically moves your task from TODO to IN PROGRESS when you push the branch.

2. ClickUp automatically moves your task from IN PROGRESS to IN REVIEW when you create a PR. ClickUp automatically moves your task from IN REVIEW to IN STAGING when the PR is merged.

3. Github will link to the ClickUp task in the PR.

Reviewing Code

Reviewing code earnestly is the single most important thing we can do to ensure the quality of our products, the maintainability of our technology, and knowledge share among the team.

Process

PRs should be created for every change, no matter how small. This enforces discipline on us and prevents us from going down a slippery slope of not getting things reviewed, not catching bugs, letting them get into production, and building a low-quality product.

When reviewing a PR, you should first verify it works as expected. On web, this means running the code locally or via a preview build. On BE, this means running it locally and/or simply verifying the functionality is covered adequately with unit tests.

Naming PRs

If you created a branch using ClickUp as above, the PR title will automatically be named:

CU-{{id}}/{{title}}/{{owner}}

Including the ClickUp ID in the PR title creates an audit trail so we can easily refer to the original issue.

What to Look For?

Clear purpose / intent:

• Unclear code: many reasons why something could be unclear; anonymous complex regexp, poor naming, mega-functions, lack of commenting, etc. Think as much as you can about the next dev or even future you! Code is read 10x more than it's written.

• Unnecessary code: for example, over-abstraction to the point of getting in the way, code broken out into a function for no reason, etc; TypeScript provides a slew of functionality (utility types, generics, type literals, etc) to prevent things getting complex

• Appropriateness: does the fix make sense in the context of the wider code / service / api / module / feature? Sometimes diving into a small fix can miss the wider context (this should also be addressed at the planning stage)

• Code that misses the point: is this a problem that even needs to be solved? Less code is better than more code, no code better than less code; review the big picture as well as the small picture to make sure we're not writing code that could remain unwritten

Reasonable code reuse:

• Repeated code: does it make sense to abstract it away to enable cleaner and more maintainable code?

• Before adding a new dependency, check if similar library already being used

• Before creating utility function, search if there are relevant functions already created

Consistency:

• Ensure file and directory naming is consistent with repo

• Ensure component and classnames are consistent with repo

• Ensure folder structure is consistent with repo

• One class or component per file for easiest searchability

• Clearly / consistently-named variables (where possible!) especially across related functions

Housekeeping:

• Logical / functional errors

• Commented code: we can always go back to old code; no need to clutter code base with commented code

• Minor cleanups: if something can be cleaned up without affecting the functionality (i.e. risking a new bug); just do it

Support:

• Automated tests: should cover at least the happy path and the most common error paths.

• Documentation: were the functions commented helpfully, would they benefit from doc comments, does the feature require additional markdown documentation?

If making suggestion or criticism, try to add example or short code snippet on better way to do things.

Some Specific Things to Look For

• For list of items `

• ` , use `key` attribute for each one

• Use named exports always to remove ambiguity when importing

• Poor typing or `@ts-ignore`; the compiler is your friend; understand any errors and mitigate

• Missing types / generics: many functions can be typed using generics; missing this is akin to typing as `any` so you lose type safety

Who Should Merge?

A PR should signal an intent that you want to merge your code. As the author, if the code is not ready to merge, you should add a label like DON'T MERGE or WIP or leave it as a draft PR. If a reviewer approves of your PR, all CI checks pass, it has been tested, and the reviewer hasn't made any comments / suggestions then the reviewer should just merge it in.

If the reviewer approves, but leaves some small comments/suggestions, the reviewer should leave it to the author to either merge on their own or address the comments first.

Reviewers can also turn on 'auto merge' to merge a PR as soon as all build checks (tests, linting, approvals, conflicts) are resolved.

Review PRs in a Timely Fashion

If everyone on the team reviews PRs at least when they start work for the day and when they finish work for the day, we will ensure that no PR languishes in a non-reviewed state for more than 12 hours or so.

The faster we can review each other's code the better as we want to avoid developer context switching as much as possible. Also, the faster we review each other's code, the less likely it is that there will be conflicts to fix, which can be a source of frustration and bugs. Of course, if you are in deep focus, you should not drop that focus to review code unless it's an emergency.

Conclusion

This is a living document. Feel free to comment or make suggestions. Looking forward to building an awesome engineering team and an awesome product with you!

Setting up generative AI for Space Runners involves many steps and technologies. A previous blog post on our tech stack mentions some of the tools we are using at the code level. Today, we will focus more on the MLOps/DevOps aspects of how things work in Google Kubernetes. We will first explain why we chose Kubernetes over other GCP products for hosting our models. Then, we will dive into the specifics of setting up generative AI infrastructure with Google Kubernetes Engine (GKE).

Model Serving with Google Cloud Platform

Google offers three major products for creating images with Generative AI³. In order of least to most customizable they are:

1. Google Imagen/Gemini

2. Vertex AI

3. Google Kubernetes Engine (GKE)

At the time we set up our Ablo website, Imagen/Gemini did not produce images of sufficient quality for our use case in fashion. The images contained artifacts, did not adhere closely to prompts, and could not be styled with training data. This may change in the future, but for the time being, it’s not a viable option for us.

Vertex AI vs Manual Setup in GKE

Although VertexAI is a powerful platform, abstracting away a lot of GKE’s complexity, it is still has some severe limitations and we ultimately chose to setup our models manually in GKE. For quick reference, here is a list of pros and cons that summarize our experience with the two services.

Vertex AI Pros

• Fully managed node scaling

• Built-in latency monitoring

• Automatic request queue handling

Vertex AI Cons

• Poor visibility into debugging logs

• Arbitrary and non-configurable timeouts and size limits

GKE Pros

• Proven track record with 10 years of general access

• Popular with lots of support

• Versatile

GKE Cons

• Relatively complex

• Requires a lot of manual setup and monitoring

The Vertex AI documentation does not make it very clear that deploying custom docker containers is an option for inference. The documentation for this is in the "custom training" section.

For our particular use-cases, the biggest limitation we ran into with Vertex AI is that we could not configure readiness checks and timeouts to give our docker containers enough time to load the neural network checkpoint data (see the next section for more details on that topic). With poor visibility into the logs for Vertex AI, rather than go back and forth with GCP support, we switched to GKE.

Google Kubernetes Setup

Storage

Checkpoints for SDXL models, including Control Nets, LoRAs for styling, IP-Adapters, and other components, range between 15GB and 70GB. Including these files in a Docker image will result in long build, push, and startup times. The best approach to handle this is to store all the checkpoints in a folder and add that folder to a .dockerignore file. Then, add code to load the checkpoints from a storage bucket once the Docker container starts up in GKE or another context.

At a high level the process looks like the figure below,

The GCP Artifact Registry stores the docker images for the model servers. GKE takes these images to spin up pods. After the pods have started up, they fetch model weights and other data from cloud storage using a gcloud storage cp command.

Request Flow

Information about image styles and the prompt engineering that goes around that need to be easy to edit. The backend API services handles fetching this type of information from our Postgres database (see our tech stack). The backend service then creates a request and passes it along to GKE.

It’s also important to note that the ML serving instances on GKE are much more expensive to run at $5+ per hour versus the machines that run the backend services, so we want to minimize compute time on the ML instances as much as possible.

In the diagram above, numbers inside the arrows indicate the order of execution. For some workflows like our photo transformer, we need to use secondary services like an image captioning model. Since these only ever are called by the generative AI service, they are not exposed outside of GKE.

Observability and Alerting

GKE offers versatile observability and alerting tools. For machine learning inference, the most useful so far have been Cloud Trace and log-based metrics. Cloud trace allows us to look at the run time of requests, and then investigate all the logs associate with the request. To achieve this, we use python’s opentelemetry.

Log-based metrics help us setup dashboards and watch the distribution of inference times. The 95th and 99th quantiles help us get an idea of what inference times are in the worst-case scenarios.

Choosing the Right Hardware

Our goal is to try to get inference times on the order of 10 seconds—the time at which most people will lose focus to something else². Running SDXL, or any large diffusion model without distillation, in that time-frame requires a GPU or more specialized hardware, such as TPUs and FPGA. Our customization requirements however make it very difficult to compile our workflows for more specialized hardware. This makes Nvidia GPUs our hardware of choice. This is also part of the reason we went to GCP rather than AWS: The options for mid-range data center GPUs are more numerous.

SDXL, with all of the control nets, LoRAs, and IP-adapters that we are loading use up anywhere from 20 to 40 GB of GPU VideoRAM. So the GPUs we have to choose from are:

• Nvidia L4 (24 GB VRAM)

• Nvidia A100 (40 GB VRAM)

• Nvidia A100 “Ultra” (80 GB VRAM)

The L4 is much cheaper than the A100, especially on a cost per GB of VRAM. Anything we can fit on the L4, we run on an L4; however, at least two of our major workflows require more VRAM.

Nvidia GPU sharing comes in handy here because it makes it possible to have multiple GKE pods share a graphics card. For all of the extra-large workflows that do not fit in the L4 GPU, we have A100 “Ultra” configured to share 2 pods providing 40 GB of VRAM each.

Conclusion

Setting up generative AI inference pipeline in Google Cloud’s Kubernetes Engine was a challenge that spanned the course of several weeks (and months of maintenance and perfecting). It has proven itself as powerful and reliable platform giving us all the options we need to create images for our platform.

After deciding all the architecture and systems for our workflows, the next challenge is to write code and build docker containers. This is something we will examine in a future blog post, so stay tuned!

1. Hugo Huang, Harvard Business Review. What CEOs Need to Know About the Costs of Adopting GenAI

2. Jakob Nielsen, UX Tigers Blog. The Need for Speed in AI

3. Google Cloud. AI and machine learning products

SpaceRunners has a design tool where artists can create custom designs in a limited drawing area on any physical object. For example, the SpaceRunners team can upload an image of a T-Shirt and set it as a template. Inside this T-Shirt you can only design on a predefined area as shown in the image below:

This image shows a part of the SpaceRunners admin where one can position the drawing area inside the template and set its width and height. This area makes sense in the context of bringing these designs to the real world, for example printing the T-Shirt. Design elements that go outside of this area will be cut off when the design is exported.

On the frontend, SpaceRunners is using Fabric.js to power its design tool. Fabric.js provides an object model on top of the HTML canvas element to help build canvas experiences faster, with less code and in a more maintainable way. More information can be found in their docs. This article will describe a very well designed UX flow for how to achieve the requirements explained above and also how it can be done with Fabric.js. There's no straightforward API for this and figuring it out took some time so we hope this article will be helpful to others.

UI considerations to create a seamless user experience

The canvas has to span the full width and height of its container inside the editor. In the image below the canvas is the entire area in gray, below the editor tools and next to the image generation tools.

This allows for two things:

1. When an object on the canvas goes outside of the drawing area although the object itself is cut off, the resize and rotate controls should still be visible. Since those controls are canvas based everything around the drawing area also has to be a canvas

2. The canvas can be zoomed in and out where the entire background object and the design elements zoom together.

An easy to implement approach would be to have the background image as an HTML element and then absolutely position the drawing area on it using the coordinates from the admin. In this case only the drawing area would be the canvas. Looking at this approach through the lens of the two requirements above, this would mean that controls wouldn't be visible outside of the drawing area and the background image wouldn't zoom together with the canvas.

The approach to achieve the desired result

1. Set a background image on the canvas using its setBackgroundImage function. This makes the background image a part of the canvas and can be zoomed in and out together with everything else

2. Add a Fabric.js clip path to the canvas. A Fabric.js canvas object has a clipPath property where any shape can be place. When objects on the canvas go outside of the clip path they're clipped.

3. Add an overlay image to the canvas using the setOverlayImage from Fabric.js

4. Set an inverted clip path to this overlay image. An inverted clip path cuts off everything except the shape it has been defined for it. The reason for this inverted clip path is to prevent the original clip path from also cutting off the background image.

Here's the code:

export const setBackgroundImage = (canvas, img, isMobile) => {
  // The clipPath object here has been previously set based on the settings for the template
  const { clipPath, width, height, wrapperEl } = canvas;

  // This calculates the background image width to fit inside the container
  const { clientHeight, clientWidth } = wrapperEl;

  const aspectRatio = clientWidth / clientHeight;

  const imageWidth =
    (canvas.width *
      (isMobile
        ? GARMENT_IMAGE_MOBILE_WIDTH
        : clientHeight * PERCENTAGE_OF_CONTAINER_HEIGHT * aspectRatio)) /
    clientWidth;

  img.scaleToWidth(imageWidth);

  img.set({
    left: width / 2,
    top: height / 2,
    originX: 'center',
    originY: 'center',
    selectable: false,
    centeredScaling: true,
    erasable: false,
    excludeFromExport: true,
  });

  canvas.renderAll();

  const oldClipPath = { ...clipPath };

  canvas.clipPath.top = clipPath.templateBasedTop;

  // This positions the clip path based on current container size because the canvas is responsive to container dimensions changes
  scaleObjectTops(canvas, oldClipPath);

  canvas.setBackgroundImage(img).renderAll();

  // This adds the overlay background image which prevents the original background image from being clipped by the clip path
  img.clone((copy) => {
    const clipPath2 = new fabric.Rect({
      height: clipPath.height - 2,
      selectable: false,
      stroke: 'transparent',
      strokeWidth: 0,
      width: clipPath.width - 2,
      left: clipPath.left + 1,
      top: clipPath.top + 1,
      inverted: true,
      absolutePositioned: true,
      excludeFromExport: true,
    });

    copy.set({
      clipPath: clipPath2,
    });
    canvas.setOverlayImage(copy).renderAll();
  });
};

Here’s the end result visually:

Conclusion

The code for your app will look different depending on how complex you want your experience to be, but you can reuse the code provided here to achieve this particular pattern with minor adjustments.

Feel free to go try it out at ablo.ai. We’re currently offering 1000 free credits to use our AI design tools.

In future articles we'll explain more Fabric.js concepts and how to achieve other complex behaviors.

Here’s our opinionated tech stack, starting from the frontend and going all the way back to our image generation services.

Frontend (web)

We have 2 websites we’re actively maintaining and updating:

1. ablo.ai: Our core image generation and community design (and soon to be e-comm) product.

2. spacerunners.com: Our informational, inspirational site for the company.

Stack

• Analytics: Segment → Amplitude
  Segment is great for piping your user data and analytics to multiple places and Amplitude is great for capturing the important events for your User’s behavior.

• Canvas manipulation: Fabric.js
  Fabric makes it easy to work with the HTML Canvas

• Customer Services: Intercom
  We integrate Intercom into our sites so customers can easily chat with us.

• Deployment: Render
  Render is free to host and deploy static sites and also gives us preview builds on pull requests, which is super handy for testing before we merge in code.

• Error reporting: Sentry
  Sentry is great for catching issues in production and we use it full-stack as well.

• Framework: React.js
  In our opinion, React is still the easiest framework to build fast in and has a huge community and toolset supporting it.

• Language: Typescript
  We are full stack Typescript. This allows our FE developers to more easily work on the BE.

• Real-time: Pubnub
  Pubnub provides a simple API to get real-time notifications, such as when credits are used on our your account.

• Styling: Chakra UI
  Chakra is a full UI and styling library that enables us to build and style components super quickly (once you learn the basics :) )

Services Backend (API)

Our Services BE powers our public API used by Clients all over the world in their design tools and also internally for us in ablo.ai.

Stack

• Analytics: Segment → Amplitude
  Segment is great for piping your user data and analytics to multiple places and Amplitude is great for capturing the important events for your User’s behavior.

• API Docs: Readme
  Readme integrates nicely with our OpenAPI definitions that are generated automatically from our annotations in our Nest app.

• Cache: Redis
  We cache responses in Redis to some of those heavy queries where the response doesn’t change often. This speeds up our system and reduces the load on our Postgres DB.

• Deployment: Render
  Render makes it really easy to do CI/CD and includes our Postgres and Redis stores as well.

• DNS: Cloudflare
  Cloudflare provides a nice proxy to all our endpoints and also provides out of the box DDoS protection.

• E-comm: Shopify
  Shopify enables us to easily set up a headless store, integrates nicely with our printing and shipping partner (Printful), and handles all the payments for us.

• Error reporting: Sentry
  We use Sentry full-stack for error reporting to catch issues in production.

• File store: GCP Storage
  We store images mostly in GCP Storage as that’s where our image generation workflows (e.g. Image Maker, Fontmaker, and Photo Transformer) live. GCP Storage is also great because they have a feature that automatically moves files to cold storage if they haven’t been used in a while.

• Framework: Nest.js
  Nest gives us an easy to use modular framework for cleanly separating services in our monolithic BE, defining RESTful endpoints, generating API docs, and running scheduled jobs.

• Language: Typescript
  We are full-stack Typescript. Allows our BE devs to more easily work on the FE.

• Printing & Shipping: Printful
  Printful has a huge catalogue and enables us to send custom designs via API to get printed and shipped.

• Real-time: Pubnub
  We call a simple Pubnub API to notify all Users when credits have been used on their Client.

• Email: Sendgrid
  We use Sendgrid for sending transactional emails from our System via API.

• Subscriptions: Stripe
  Stripe enables us to easily set up monthly credit subscriptions with overage charges and handles all the billing for us.

• Transactional data store: Postgres
  Postgres is a tried and true, scalable, relational database. As we’ve scaled, we have had some performance issues with complex queries involving a lot of joins, and have had to make optimizations here and there to our queries and call patterns, but that’s part of the game.

Machine Learning Backend (AI)

We use machine learning / AI to do a number of things, mostly related to image generation and manipulation:

• Image Maker: Our text to image service

• Font Maker: Our text to graphic font service

• Photo Transformer: Our image to image service

• Background removal

• Upscale

We’re always experimenting with the best way to do these things and the landscape is changing rapidly under our feet, but our current stack is something like this:

• Background removal: BiRefNet
  BiRefNet (bi-direction recurrent feature network) is a performant, open-source, background removal library that doesn’t need a GPU.

• Deployment: Google Kubernetes Engine
  GKE enables us to build our custom AI workflows in containers and utilize GPUs from GCP.

• Image generation engines: Stable Diffusion and Flux
  Stable Diffusion gives us the best combination of customizability and quality. Flux is a great combination of speed and quality.

• Image storage: GCP Storage
  GCP Storage is great because they have a feature that automatically moves files to cold storage if they haven’t been used in a while.

• Language: Python
  All the hip machine learning and AI libraries are written in Python. It also has image manipulation libraries.

• Models: Hugging Face
  Hugging Face has an easy to use repository of models to experiment with and a great community.

• Training: Replicate
  For custom style training, we use Replicate to train LoRAs and do inference.

• Upscale: SupIR
  SupIR (Super-Resolution using Iterative Refinement) is a great open source library for upscaling as it enables us to upscale to 16MP for high quality printing while preserving details from the original image.

That’s a wrap! Let me know if there’s anything here you’d like to learn more about, and we’ll write a follow up post and go in depth.

Space Runners is a fashion-tech platform revolutionizing how you design, collaborate, and launch fashion collections across both physical and digital realms. We do this by using modern AI and web3 technologies.

Our blog will be your window into the innovative work happening at Space Runners. Through these posts, we’ll share insights, behind-the-scenes looks, and exciting updates on what we’re building.

Our Mission

Our mission is simple: to create the most intuitive tools that empower anyone to innovate, collaborate, and grow in the fashion industry.

Our core tool and product is called ablo.ai. On ablo.ai, we’re building a community powered collaborative design tool that enables anyone to create and sell their own designs.

The Team

Our tech team is small but mighty, composed of experts across multiple fields:

• 1 CTO

• 1 FE focused full-stack engineer

• 1 BE focused full-stack engineer

• 1 machine learning engineer

• 1 technical artist

Our Core Values

We have a set of core values that we try to live every day:

• Creativity
  We push the boundaries of creativity with cutting-edge technology, always testing, learning, and evolving.

• Collaboration
  We value working together wherever we are around the world. We value good communication and we value other people’s perspectives.

• Ownership
  We give and expect ownership of things end to end. If you don’t like it, speak up!

• Inclusivity
  We employ empathy in everything we do and ensure everyone is included.

• Fun
  Enjoy the journey!

That’s a wrap!

In future posts, we’ll go deep into our tech stack, how we work, and how we utilize AI especially to do magic.

Want to stay in the loop? Subscribe to our newsletter for the latest updates and insights straight to your inbox!