Angular

How to set up screenshot comparison testing with cypress inside an NX workspace

Published Aug 6, 2021

Updated Feb 14, 2023

6 min read

This article was written over 18 months ago and may contain information that is out of date. Some content may be relevant but please refer to the relevant official documentation or available resources for the latest information.

I have encountered several projects where visual testing was done manually. On those projects, typically, a lot of visual changes made it to production, and then came back as bugs. Recently, I needed to set up automated visual testing on an NX project to make it safer for us to refactor CSS. In this blog post, I'd like to show you how to set up screenshot comparison tests with Cypress inside an NX workspace.

I have done a JS Marathon episode back in March, where I wrote some Cypress tests. I updated the dependencies on that project, and I'll use that repository as an example for this blog post. Feel free to check it out.

What is snapshot testing?

Snapshot or screenshot comparison tests work based on comparing images pixel-by-pixel. For them to work, we need to have baseline images, which are taken during the first test run. However, these tests can be extremely flaky. The first issue comes from the fact, that a screenshot taken on a Windows machine will certainly be different from a screenshot taken on a Mac. It can even differ when you take the same screenshot on different monitors, or if you change color profiles between two tests on the same monitor.

Even if you make sure that the same configuration is set on both machines. Take into account that, for example, scrollbars look different on different operating systems. We are going to mitigate this problem using Docker, which will run your tests on a Linux os every time. Let's jump right into it!

Install dependencies

For our comparison tets, we are going to use the cypress-image-snapshot package with its type declarations.

npm install --save-dev cypress-image-snapshot @types/cypress-image-snapshot

After that, we need to register the plugin for our Cypress tests. Let's register the plugin for our cypress-functional tests, by adding the following to the plugins/index.js file:


const { preprocessTypescript } = require('@nrwl/cypress/plugins/preprocessor');
const { addMatchImageSnapshotPlugin } = require('cypress-image-snapshot/plugin');

module.exports = (on, config) => {
  // we register our plugin using its register method:
  addMatchImageSnapshotPlugin(on, config);

  on('file:preprocessor', preprocessTypescript(config));

  // force color profile
  on('before:browser:launch', (browser = {}, launchOptions) => {
    if (browser.family === 'chromium' && browser.name !== 'electron') {
      launchOptions.args.push('--force-color-profile=srgb');
    }
  });
};

We also added a special launchOption to our chrome browsers. The --force-color-profile=srgb will ensure that the same colour profile is used inside a Docker container, and in our CI. Since screenshots taken on different devices will differ from each other, we need to make sure that we can reproduce the exact environment every time we test for screenshots. This is also the reason why we don't want to take screenshots while we write our tests using the test runner.

Now, we need to register the matchImageSnapshot command, which we can do in the support/commands.ts file:

import { addMatchImageSnapshotCommand } from 'cypress-image-snapshot/command';

declare namespace Cypress {
  interface Chainable<Subject> {
    /**
     * Custom command to match image snapshots.
     * @example cy.matchImageSnapshot('greeting')
     */
    matchImageSnapshot(snapshotName?: string): void;
  }
}

// We set up the settings
addMatchImageSnapshotCommand({
  customSnapshotsDir: 'src/snapshots',
  failureThreshold: 0.05, // threshold for entire image
  failureThresholdType: 'percent', // percent of image or number of pixels
  customDiffConfig: { threshold: 0.1 }, // threshold for each pixel
  capture: 'viewport' // capture viewport in screenshot
});

// We also overwrite the command, so it does not take a sceenshot if we run the tests inside the test runner
Cypress.Commands.overwrite('matchImageSnapshot', (originalFn, snapshotName, options) => {
  if (Cypress.env('ALLOW_SCREENSHOT')) {
    originalFn(snapshotName, options)
  } else {
    cy.log(`Screenshot comparison is disabled`);
  }
})

Now, we have registered the command that will take care of our screenshot-comparison. We are going to use specifically defined environment variables to trigger screenshot matching. And if the environment does not allow taking screenshots, a log entry will be added to the test.

Our baseline images will be recorded inside the apps/customer-functional/src/snapshots/ folder, which we added to our configuration using the customSnapshotsDir property. NX will run the tests inside the apps/customer-functional folder, so we need to set the path as if we were inside that folder.

Let's open our integration/1-pizza-list.spec.ts file, and add our command to the end of our first test:

// ...
it(`a message should be displayed`, () => {
  // we get the error message that has the data-test-id
  cy.get(`[data-test-id="no delivery"]`)
    .should('exist')
    .and('be.visible')
    .and(
      'contain',
      'Sorry, but we are not delivering pizzas at the moment.'
    );

  // we take the screenshot
  cy.matchImageSnapshot('Empty pizza list')
});

Now, if we run our tests using the npm run functional:customer:debug command, the cypress test runner will open, but the screenshot will not be recorded, because the ALLOW_SCREENSHOT environment variable is undefined.

Set up configurations

Let's edit our apps/customer-functional/cypress.json file, and add the following:

{
  "env": {
    "ALLOW_SCREENSHOT": false
  },
  // ...
}

Now, we copy the contents of the config file, and create a new config file with the cypress.snapshot.json name, where we set the ALLOW_SCREENSHOT variable to true.

{
  "env": {
    "ALLOW_SCREENSHOT": true
  },
  // ...
}

Now, we should set up a snapshot configuration in our angular.json file. Please note, that in NX projects not using the Angular-CLI, the workspace.json file needs to be edited.

We search for our project config, which is under customer-functional, and modify the "e2e" config object under "architect" ("targets" in React based NX monorepos). We add a new entry under the "configurations" object as follows:

"configurations": {
  "production": {
    "devServerTarget": "customer:serve:production"
  },
  "snapshot": {
    "cypressConfig": "apps/customer-functional/cypress.snapshot.json"
  }
}

Now, if we run npm run e2e customer-functional --configuration=snapshot, baseline images will be generated for our test. But we don't want to do that just yet.

Run the tests inside Docker

The Cypress team maintains docker images, which make our lives easier when we want to run our tests in CI/CD. The cypress/included images contain cypress, and they are set up to run cypress run, and then exit when the tests finish running. In an NX workspace, we run Cypress tests with other commands. Let's create our own Dockerfile inside our tools/snapshot-comparison folder. At the time of writing this article, the latest cypress version is 8.0.0, so we are going to use that as a base:

FROM cypress/included:8.0.0

ENTRYPOINT ["npm", "run", "snapshot:customer-functional"]

When we build this image, we can use it as a container. It will run the npm run snapshot:customer-functional command, which will run the cypress tests on our customer front-end. We set this script up in our package.json:


{
  "scripts": {
    // ...
      "snapshot:customer-functional": "npm run e2e --skip-nx-cache --configuration=snapshot customer-functional",
    // ...
  }
}

We want to run these tests without caching. That is why we added the --skip-nx-cache, and we run the tests with the snapshot configuration for the customer-functional project. Let's build our Docker image:

docker build . -f tools/snapshot-comparison/Dockerfile -t snapshot-testing

With this command, we run the docker build process from the root directory of the project. The -f flag sets the Dockerfile we want to build, and the -t flag will name the image. After the image is built, if we run docker images we can see that we have the snapshot-testing image.

Let's add two more scripts to our package.json. One for running screenshot comparison tests locally inside Docker, and one for updating existing snapshots.

{
  "scripts": {
    // ...
    "snapshot:customer-functional:docker": "docker run -it --rm -e CYPRESS_updateSnapshots=%CYPRESS_updateSnapshots% -v $PWD:/cypress -w /cypress snapshot-testing",
    "snapshot:customer-functional:update-snapshots": "CYPRESS_updateSnapshots=true npm run affected:e2e:snapshot",
    // ...
  }
}

The CYPRESS_updateSnapshots environment variable tells the cypress-image-snapshot plugin to overwrite the existing baseline images. This comes in handy when you need to make changes to the UI, and you need to update the snapshots for future reference. We pass this as an environment variable to our Docker container using the -e flag. The -it flag will make sure that you see the logs during the run in your terminal. The --rm will remove the container when the process exits, even if it is a non-zero exit code. With the -v $PWD:/cypress flag, we mount our project as a volume inside the container into its /cypress folder. Then, with the -w cypress flag, we set the working directory inside the container to the /cypress folder. This is necessary since we can't mount a volume into the root directory of a container. The snapshot:customer-functional:update-snapshots command sets the CYPRESS_updateSnapshots environment variable to true, and runs the first command.

Please note that these commands will not work on a Windows machine. Instead of $PWD:/cypress you need to use %cd%:/cypress when you run it from the command line. For updating snapshots, setting an environment variable works differently as well: set CYPRESS_updateSnapshots=true && npm run e2e:docker.

After we run the snapshot:customer-functional:docker command, we can see that there's a baseline image generated inside the apps/customer-functional/src/snapshots/1-pizza-list.spec.ts/ folder.

Now, let's pretend that we accidentally replaced the background-color property of the header from darkred to blue. When we run the tests again, there is going to be a __diff_output__ folder generated with the diff images. The diff image contains the baseline image (from left to right), the differences, and the current image.

If changing the color of the header is not a mistake (ex: the client requests us to change the design of the page), we can just run snapshot:customer-functional:update-snapshots, and then commit the changed baseline images.

This Dot is a consultancy dedicated to guiding companies through their modernization and digital transformation journeys. Specializing in replatforming, modernizing, and launching new initiatives, we stand out by taking true ownership of your engineering projects.

We love helping teams with projects that have missed their deadlines or helping keep your strategic digital initiatives on course. Check out our case studies and our clients that trust us with their engineering.

About the author(s)

Balázs Tápai
He is a Software Engineer with a passion for automated testing. He loves Angular on the Front-End and NestJS on the Back-End. He also uses Cypress to reduce developer anxiety before demo meetings.
@TapaiBalazs @TapaiBalazs

Harnessing the Power of Threlte - Building Reactive Three.js Scenes in Svelte

Introduction Web development has evolved to include immersive 3D experiences through libraries like Three.js. This powerful JavaScript library enables the creation of captivating 3D scenes within browsers. Three.js: The 3D Powerhouse Three.js democratizes 3D rendering, allowing developers of all skill levels to craft interactive 3D worlds. Svelte Ecosystem: Svelte Cubed and Svelthree The Svelte ecosystem presents solutions like Svelte Cubed and Svelthree, which bridges Svelte with Three.js, offering streamlined reactivity for 3D web experiences. Introducing Threlte v6: Uniting SvelteKit 1.0, Svelte 4, and TypeScript Threlte v6 is a rendering and component library for Svelte that seamlessly integrates Three.js. By harnessing TypeScript's types, it provides a robust and delightful coding experience. In this tutorial, we'll showcase Threlte's capabilities by building an engaging website header: an auto-rotating sphere that changes color on mouse down. Using Threlte v6, SvelteKit 1.0, and Three.js, we're set to create a visually stunning experience. Let's dive in! Setting up Threlte Before building our scene, we need to set up Threlte. We can scaffold a new project using the CLI or manually install Threlte in an existing project. Option 1: Scaffold a New Threlte Project Create a new SvelteKit project and install Threlte with: ` Option 2: Manual Installation For an existing project, select the necessary Threlte packages and install: ` Configuration adjustments for SvelteKit can be made in the "vite.config.js" file: ` With Threlte configured, we're ready to build our interactive sphere. In the next chapter, we'll lay the groundwork for our exciting 3D web experience! Exploring the Boilerplate of Threlte Upon scaffolding a new project using npm create threlte, a few essential boilerplate files are generated. In this chapter, we'll examine the code snippets from three of these files: lib/components/scene.svelte, routes/+page.svelte, and lib/components/app.svelte. 1. lib/components/scene.svelte: This file lays the foundation for our 3D scene. Here's a brief breakdown of its main elements: - Perspective Camera: Sets up the camera view with a specific field of view and position, and integrates OrbitControls for auto-rotation and zoom management. - Directional and Ambient Lights: Defines the lighting conditions to illuminate the scene. - Grid: A grid structure to represent the ground. - ContactShadows: Adds shadow effects to enhance realism. - Float: Wraps around 3D mesh objects and defines floating properties, including intensity and range. Various geometrical shapes like BoxGeometry, TorusKnotGeometry, and IcosahedronGeometry are included here. 2. routes/+page.svelte: This file handles the ui of the index page and imports all necessary components we need to bring our vibrant design to life. 3. lib/components/app.svelte: This file is where you would typically define the main application layout, including styling and embedding other components. Heading to the Fun Stuff With the boilerplate components explained, we're now ready to dive into the exciting part of building our interactive 3D web experience. In the next section, we'll begin crafting our auto-rotating sphere, and explore how Threlte's robust features will help us bring it to life. Creating a Rotating Sphere Scene In this chapter, we'll walk you through creating an interactive 3D sphere scene using Threlte. We'll cover setting up the scene, the sphere, the camera and lights, and finally the interactivity that includes a scaling effect and color changes. 1. Setting Up the Scene First, we need to import the required components and utilities from Threlte. ` 2. Setting Up the Sphere We'll create the 3D sphere using Threlte's and components. ` 1. : This is a component from Threlte that represents a 3D object, which in this case is a sphere. It's the container that holds the geometry and material of the sphere. 2. : This is the geometry of the sphere. It defines the shape and characteristics of the sphere. The args attribute specifies the parameters for the sphere's creation: - The first argument (1) is the radius of the sphere. - The second argument (32) represents the number of width segments. - The third argument (32) represents the number of height segments. 3. : This is the material applied to the sphere. It determines how the surface of the sphere interacts with light. The color attribute specifies the color of the material. In this case, the color is dynamic and defined by the sphereColor variable, which updates based on user interaction. The roughness attribute controls the surface roughness of the sphere, affecting how it reflects light. 3. Setting Up the Camera and Lights Next, we'll position the camera and add lights to create a visually appealing scene. ` 1. : This component represents the camera in the scene. It provides the viewpoint through which the user sees the 3D objects. The position attribute defines the camera's position in 3D space. In this case, the camera is positioned at (-10, 20, 10). The fov attribute specifies the field of view, which affects how wide the camera's view is. - makeDefault: This attribute makes this camera the default camera for rendering the scene. 2. : This component provides controls for easy navigation and interaction with the scene. It allows the user to pan, zoom, and orbit around the objects in the scene. The attributes within the component configure its behavior: - enableZoom: Disables zooming using the mouse scroll wheel. - enablePan: Disables panning the scene. - enableDamping: Enables a damping effect that smoothens the camera's movement. - autoRotate: Enables automatic rotation of the camera around the scene. - autoRotateSpeed: Defines the speed of the auto-rotation. 3. : This component represents a directional light source in the scene. It simulates light coming from a specific direction. The attributes within the component configure the light's behavior: - intensity: Specifies the intensity of the light. - position.x and position.y: Define the position of the light source in the scene. 4. : This component represents an ambient light source in the scene. It provides even lighting across all objects in the scene. The intensity attribute controls the strength of the ambient light. 4. Interactivity: Scaling and Color Changes Now we'll add interactivity to the sphere, allowing it to scale and change color in response to user input. First, we'll import the required utilities for animation and set up a spring object to manage the scale. ` We'll update the sphere definition to include scaling: ` Lastly, we'll add code to update the color of the sphere based on the mouse's position within the window. ` We have successfully created a rotating sphere scene with scaling and color-changing interactivity. By leveraging Threlte's capabilities, we have built a visually engaging 3D experience that responds to user input, providing a dynamic and immersive interface. Adding Navigation and Scroll Prompt in app.svelte In this chapter, we'll add a navigation bar and a scroll prompt to our scene. The navigation bar provides links for user navigation, while the scroll prompt encourages the user to interact with the content. Here's a step-by-step breakdown of the code: 1. Importing the Canvas and Scene The Canvas component from Threlte serves as the container for our 3D scene. We import our custom Scene component to render within the canvas. ` 2. Embedding the 3D Scene The Canvas component wraps the Scene component to render the 3D content. It is positioned absolutely to cover the full viewport, and the z-index property ensures that it's layered behind the navigation elements. ` 3. Adding the Navigation Bar We use a element to create a horizontal navigation bar at the top of the page. It contains a home link and two navigation list items. The styling properties ensure that the navigation bar is visually appealing and positioned correctly. ` 4. Adding the Scroll Prompt We include a "Give a scroll" prompt with an element to encourage user interaction. It's positioned near the bottom of the viewport and styled for readability against the background. ` 5. Styling the Components Finally, the provided CSS styles control the positioning and appearance of the canvas, navigation bar, and scroll prompt. The CSS classes apply appropriate color, font, and layout properties to create a cohesive and attractive design. ` Head to the github repo to view the full code. Check out the result: https://threlte6-spinning-ball.vercel.app/ Conclusion We've successfully added navigation and a scroll prompt to our Threlte project in the app.svelte file. By layering 2D HTML content with a 3D scene, we've created an interactive user interface that combines traditional web design elements with immersive 3D visuals....

Aug 14, 2023

6 mins

Svelte

A Deep Dive into SvelteKit's Rendering Techniques

A Deep Dive into SvelteKit's Rendering Techniques Introduction SvelteKit is a meta-framework for Svelte that allows you to develop pages based on their content. At its core, SvelteKit introduces three fundamental strategies out of the box, each designed to streamline the development process and adapt to the specific needs of your project. These strategies enable you to easily create dynamic, responsive, and highly interactive web applications. These strategies, or as SvelteKit calls them, page options, are: * Prerender: Ideal for static content that doesn't change, making your pages lightning-fast to load. * SSR (Server-Side Rendering): Ideal for rendering full pages with dynamic content from a server. * CSR (Client-Side Rendering): Best for highly dynamic and interactive applications where content updates frequently based on user actions. These page options can be applied to specific pages (when exported from **+page.js or +page.server.js) or to a group of pages (when exported from +layout.js or +layout.server.js). They can also be set across the entire application. You accomplish this by exporting it from the root layout. It's worth noting that child layouts and pages can supersede settings from parent layouts. This means you could activate prerendering for the whole app and then turn it off for certain pages that require dynamic server rendering (SSR). In this blog post, we'll explore these page options and share some insights on how you might use them in everyday web projects. Prerendering Prerendering is akin to taking a snapshot of your web pages when you build your application; you might have heard of this as static rendering. This snapshot is then served to all users, ensuring lightning-fast load times since the server simply delivers the pre-built files without additional processing rather than dynamically generating the files for each request. This method is perfect for content that remains unchanged across visits, such as blog posts, documentation, or landing pages. In other words, pages with no dynamic content. There will be situations where you would like to avoid using this option, though. The rule of thumb is that if two different users will see different content, then this is a no-go. Other reasons are inconvenience for your needs. For example, your build times could drag if you end up prerendering tons of pages. Is that convenient to you? Well, that’s for you to decide! The prerender option is turned off by default, so we need to enable it if we want to start using it. Export the following in the +page.server.js or just +page.js: ` Likewise, if you have a group of pages, you could do the same inside a +layout.js or +layout.server.js . If your app is suitable to be all SSG (Static Side Generation), you could use adapter-static, which will output files suitable for use with any static web server. In cases where you happen to opt-in for this, you could turn off pages that need dynamic rendering: ` Another cool feature about prerendering is that pages that fetch data from server routes can automatically inherit default values during the prerendering process. This feature simplifies data management and enhances the development workflow, especially when dealing with dynamic content that needs to be prerendered with specific data sets. Let's say you have a blog where each post fetches its content from a server route when the page loads. Normally, this would require the user's browser to make a request to the server at runtime. However, with prerendering, you can have this data fetched and embedded into the page at build time. ` In this example, when the blog/[slug].sveltepage is prerendered, it makes a fetch call to /api/posts/[slug], which returns the post data. This data is then used to prerender the blog post page with the content already in place, allowing the page to load instantly for the user, with the blog post content visible even before any JavaScript is executed on the client side. There’s a third and useful option when prerendering: ` Using this option is like telling SvelteKit to make a smart guess about whether to prerender your page in advance. You're saying, "Hey SvelteKit, you decide if this page should be prerendered based on what you find about the page" SvelteKit analyzes your page and if it determines the page can be prerendered without complications, it will automatically generate a prerendered version. This process involves SvelteKit either crawling a link inside an already prerendered page, prerendering entry points or targeting pages that are specifically marked for prerendering set in entries. An example is a blog section where you post articles regularly. The blog section has a main page that lists all your blog posts and individual pages for each blog post. The structure for this might be something like: In this setup, the /blog main entry page will be prerendered automatically. However, individual blog posts at paths like /blog/[slug] will not be prerendered unless linked directly from another prerendered page. For instance, if there’s a link to /blog/some-cool-slug, like: <a href="/blog/some-cool-slug">, SvelteKit will be able to crawl that link and prerender that specific page as well. Now let’s say that you would like to prerender your latest blog post, but there's no link for SvelteKit to crawl to this page. In these cases, you can explicitly add these pages to the prerender entries list. By doing so, SvelteKit will prerender every specified entry, ensuring that the content is immediately accessible to users. You can configure the prerender entries directly in your svelte.config.js file or by exporting an entries function from a +page.js, a +page.server.js or a +server.js belonging to a dynamic route. Here’s how you can do it: ` SSR SSR is similar to prerendering. It ensures that pages are first rendered on the server. This process generates the complete HTML content, which is then sent to the client for hydration). This approach enhances the initial page load performance and SEO, providing a better user experience. Unlike prerendering, where pages are generated at build time, SSR pages are created at runtime. This key difference allows for the generation of dynamic content, making SSR particularly suited for applications that require personalized content for each user or real-time updates, such as user dashboards, e-commerce sites, and social media platforms. Similar to prerendering, SSR comes with its own set of limitations, and there are scenarios where it might not be the best choice for your project: * SSR can be expensive. It can significantly load your server, especially for high-traffic sites, as each page request involves rendering content on the server. If server resources are constrained, this could lead to performance bottlenecks. * Highly Interactive Applications: Applications that rely heavily on user interactions and real-time updates (like games or interactive tools like an admin panel) might not benefit much from SSR. CSR can provide a smoother user experience in these cases, as it minimizes server requests after the initial load. * SEO Is Not YOUR Priority: If search engine optimization isn't a key concern for your project (for example, an internal dashboard or an app behind a login), the SEO benefits of SSR might not justify the additional complexity and server demands. export const ssr = true is the option enabled by default. Thus, we can use its benefits from the start. To execute code exclusively on the server, such as fetching data from a database or an external API, SvelteKit offers a convention using +page.server.js files. This setup is ideal for server-side operations, ensuring sensitive logic and credentials are not exposed to the client. ` Note: When you employ +page.js in SvelteKit, the contained code is executed on both the server and client sides by default. However, if you intend for the code to run exclusively on the client side, you can disable SSR by setting export const ssr = false within your +page.js file. Doing so ensures that the code is only executed in the browser, adhering to client-side rendering principles and turning your app into a SPA. This is useful for cases where you don’t need the load on the server, or you don’t benefit from any of the benefits of SSR. CSR CSR plays a crucial role in making web pages interactive by hydrating them and incorporating JavaScript. JavaScript is crucial for adding interactivity to web pages—everything from animations and video players to form validations and dynamic content updates relies on JavaScript. However, there are instances where JavaScript is unnecessary. Consider a prerendered 'About' page; enabling CSR on this page could be excessive, especially if it lacks interactive elements. In such scenarios, you can streamline your page by disabling CSR that comes enabled by default, which can be done by simply doing this: ` Using this trick smartly can make your web pages load fast because downloading JavaScript is sometimes heavy. The key lies in strategically combining this approach with other rendering techniques to optimize performance and user experience. One factor to consider, though, is that turning off CSR also means you'll lose client-side routing. This requires you to depend on traditional browser navigation instead. Conclusion By thoughtfully applying these strategies, you can craft a SvelteKit application that performs exceptionally and delivers a fantastic user experience tailored to your audience's needs. Wrapping up our journey through SSR with SvelteKit. We discovered how choosing the right way to render pages (like prerendering, SSR, or CSR) is super important and can make a big difference in how well a website works. SvelteKit is awesome because it lets you pick the best method for your website. So, remember, playing with SvelteKit and these rendering methods can make your websites stand out. Use it to build websites that not only work great but are also fun and easy for people to use. Dive in, try things out, and see how your web projects can shine!...

May 1, 2024

7 mins

SvelteSEOJavaScriptWeb Performance

Introducing the express-typeorm-postgres Starter Kit

Here at This Dot, we've been working with ExpressJS APIs for a while, and we've created a starter.dev kit for ExpressJS that you can use to scaffold your next backend project. The starter kit uses many well-known npm packages, such as TypeORM or BullMQ and integrates with databases such as PostgreSQL and Redis. Kit contents The express-typeorm-postgres starter kit provides you with infrastructure for development, and integrations with these infrastructures. It comes with a working Redis instance for caching and a second Redis instance for queues. It also starts up a Postgres instance for you, which you can seed with TypeORM. The infrastructure runs on docker using docker-compose. The generated project comes with prettier and eslint set-up, so you only need to spend time on configuration if you want to tweak or change the existing rules. Unit testing is set up using Jest, and there are some example tests provided with the example controllers. How to initialise API development usually requires more infrastructure than front-end development. Before you start, please make sure you have docker and docker-compose installed on your machine. To initialize a project with the express-typeorm-postgres kit, run the following: 1. Run npx @this-dot/create-starter to run the scaffolding tool 2. Select the Express.js, TypeORM, and PostgreSQL kit from the CLI library options 3. Name your project 4. cd into your project directory, and install dependencies using the tool of your choice (npm, yarn or pnpm) 5. copy the contents of the .env.example file into a .env file With this setup, you have a working starter kit that you can modify to your needs. TypeORM and Database When we started developing the kit, we decided to use PostgreSQL as the database, because it is a powerful, open-source object-relational database system that is widely used for storing and manipulating data. It has a strong reputation for reliability, performance, and feature richness, making it a great choice for a wide range of applications. It can also handle high levels of concurrency and large amounts of data, and supports complex queries and data types. Postgres is also highly extensible because it allows developers to add custom functions and data types to the database. It has a large and active community of developers and users who contribute to its ongoing development and support. The kit uses TypeORM to connect to the database instance. We chose TypeORM because it makes it easy to manage database connections and perform common database operations, such as querying, inserting, updating and deleting data. It supports TypeScript and a wide range of databases, such as PostgreSQL, MySQL, SQLite and MongoDB, therefore if you want to be able to switch between databases, it makes it easier. TypeORM also includes features such as database migrations, which help manage changes to database schema over time, and an entity model that allows you to define your database schema using classes and decorators. Overall, TypeORM is a useful tool for improving the efficiency and reliability of database-related code, and it can be a valuable addition to any TypeScript or JavaScript project that needs to interact with a database. To seed an initial set of data into your database, run the following commands: 1. npm run infrastructure:start - this starts up the database instance 2. npm run db:seed - this leverages TypeORM to seed the database. The seed command runs the src/db/run-seeders.ts file, where you can introduce your seeders for your own needs. The kit uses TypeORM-extension for seeding. Please refer to the src/db/seeding/technology-seeder.ts file for an example. Caching Storing response data in caches allows subsequent requests for the same data to be served more quickly. This can improve the performance and user experience of an API by reducing the amount of time it takes to retrieve data from the server. It can reduce the load on the database or mitigate rate limiting on third-party APIs called from your back-end. It also improves the reliability of an application by providing a fallback mechanism in case the database or the server is unavailable or slow to respond. There is a Redis instance set up in the kit to be used for caching data. Under the hood, we use the cachified library to store cached data in Redis. The kit has a useCache method exported from src/cache/cache.ts, which requires a key and a callback function to be called to fetch the data. ` When you need to invalidate cache entries, you can use the clearCacheEntry method by supplying a key string to it. It will remove the cached data from Redis, and the next request that fetches from the database will cache the new values. ` Under the src/modules/technology folder, you can see a complete example of a basic CRUD REST endpoint with caching enabled. Feel free to use those handlers as examples for your development needs. Queue A message queue allows different parts of an application, or different applications, to communicate with each other asynchronously by sending and receiving messages. This can be useful in a variety of situations, such as when one part of the application needs to perform a task that could take a long time, or when different parts of the application need to be decoupled from each other for flexibility and scalability. We chose BullMQ because it is a fast, reliable, and feature-rich message queue system. It is built on top of the popular Redis in-memory data store, which makes it very performant and scalable. It has support for parallel processing, rate limiting, retries, and a variety of other features that make it well-suited for a wide range of use cases. BullMQ has a straightforward API and good documentation. The kit has a second Redis instance set up to be used with BullMQ, and there is a queue set up out of the box, so resource-intensive tasks can be offloaded to a background process. The src/queue/ folder contains all the configuration and setup steps for the queue. Both the queue and its worker is set up in the queue.ts file. The job-processor.ts file contains the function that will process the data. To run int in a separate thread, we must pass the path to this file into the worker: ` When to use this kit This kit is most optimal when you: - want to build back-end services that can be consumed by other applications and services using ExpressJS - need a flexible and scalable way to build server-side applications - need to deal with CPU-intense operations on the server and you need a messaging queue - need to build an API with relational data - would like to just jump right into API development with ExpressJS using TypeORM and Postgres Conclusion The express-typeorm-postgres starter kit can help you kickstart your development by providing you with a working preset. It has testing configured, and it comes with a complete infrastructure orchestrated by docker-compose....

Jan 13, 2023

5 mins

NodeJSExpress.jsTypeScriptPostgreSQL

Next.js Rendering Strategies and how they affect core web vitals

When it comes to building fast and scalable web apps with Next.js, it’s important to understand how rendering works, especially with the App Router. Next.js organizes rendering around two main environments: the server and the client. On the server side, you’ll encounter three key strategies: Static Rendering, Dynamic Rendering, and Streaming. Each one comes with its own set of trade-offs and performance benefits, so knowing when to use which is crucial for delivering a great user experience. In this post, we'll break down each strategy, what it's good for, and how it impacts your site's performance, especially Core Web Vitals. We'll also explore hybrid approaches and provide practical guidance on choosing the right strategy for your use case. What Are Core Web Vitals? Core Web Vitals are a set of metrics defined by Google that measure real-world user experience on websites. These metrics play a major role in search engine rankings and directly affect how users perceive the speed and smoothness of your site. * Largest Contentful Paint (LCP): This measures loading performance. It calculates the time taken for the largest visible content element to render. A good LCP is 2.5 seconds or less. * Interaction to Next Paint (INP): This measures responsiveness to user input. A good INP is 200 milliseconds or less. * Cumulative Layout Shift (CLS): This measures the visual stability of the page. It quantifies layout instability during load. A good CLS is 0.1 or less. If you want to dive deeper into Core Web Vitals and understand more about their impact on your website's performance, I recommend reading this detailed guide on New Core Web Vitals and How They Work. Next.js Rendering Strategies and Core Web Vitals Let's explore each rendering strategy in detail: 1. Static Rendering (Server Rendering Strategy) Static Rendering is the default for Server Components in Next.js. With this approach, components are rendered at build time (or during revalidation), and the resulting HTML is reused for each request. This pre-rendering happens on the server, not in the user's browser. Static rendering is ideal for routes where the data is not personalized to the user, and this makes it suitable for: * Content-focused websites: Blogs, documentation, marketing pages * E-commerce product listings: When product details don't change frequently * SEO-critical pages: When search engine visibility is a priority * High-traffic pages: When you want to minimize server load How Static Rendering Affects Core Web Vitals * Largest Contentful Paint (LCP): Static rendering typically leads to excellent LCP scores (typically < 1s). The Pre-rendered HTML can be cached and delivered instantly from CDNs, resulting in very fast delivery of the initial content, including the largest element. Also, there is no waiting for data fetching or rendering on the client. * Interaction to Next Paint (INP): Static rendering provides a good foundation for INP, but doesn't guarantee optimal performance (typically ranges from 50-150 ms depending on implementation). While Server Components don't require hydration, any Client Components within the page still need JavaScript to become interactive. To achieve a very good INP score, you will need to make sure the Client Components within the page is minimal. * Cumulative Layout Shift (CLS): While static rendering delivers the complete page structure upfront which can be very beneficial for CLS, achieving excellent CLS requires additional optimization strategies: * Static HTML alone doesn't prevent layout shifts if resources load asynchronously * Image dimensions must be properly specified to reserve space before the image loads * Web fonts can cause text to reflow if not handled properly with font display strategies * Dynamically injected content (ads, embeds, lazy-loaded elements) can disrupt layout stability * CSS implementation significantly impacts CLS—immediate availability of styling information helps maintain visual stability Code Examples: 1. Basic static rendering: ` 2. Static rendering with revalidation (ISR): ` 3. Static path generation: ` 2. Dynamic Rendering (Server Rendering Strategy) Dynamic Rendering generates HTML on the server for each request at request time. Unlike static rendering, the content is not pre-rendered or cached but freshly generated for each user. This kind of rendering works best for: * Personalized content: User dashboards, account pages * Real-time data: Stock prices, live sports scores * Request-specific information: Pages that use cookies, headers, or search parameters * Frequently changing data: Content that needs to be up-to-date on every request How Dynamic Rendering Affects Core Web Vitals * Largest Contentful Paint (LCP): With dynamic rendering, the server needs to generate HTML for each request, and that can't be fully cached at the CDN level. It is still faster than client-side rendering as HTML is generated on the server. * Interaction to Next Paint (INP): The performance is similar to static rendering once the page is loaded. However, it can become slower if the dynamic content includes many Client Components. * Cumulative Layout Shift (CLS): Dynamic rendering can potentially introduce CLS if the data fetched at request time significantly alters the layout of the page compared to a static structure. However, if the layout is stable and the dynamic content size fits within predefined areas, the CLS can be managed effectively. Code Examples: 1. Explicit dynamic rendering: ` 2. Simplicit dynamic rendering with cookies: ` 3. Dynamic routes: ` 3. Streaming (Server Rendering Strategy) Streaming allows you to progressively render UI from the server. Instead of waiting for all the data to be ready before sending any HTML, the server sends chunks of HTML as they become available. This is implemented using React's Suspense boundary. React Suspense works by creating boundaries in your component tree that can "suspend" rendering while waiting for asynchronous operations. When a component inside a Suspense boundary throws a promise (which happens automatically with data fetching in React Server Components), React pauses rendering of that component and its children, renders the fallback UI specified in the Suspense component, continues rendering other parts of the page outside this boundary, and eventually resumes and replaces the fallback with the actual component once the promise resolves. When streaming, this mechanism allows the server to send the initial HTML with fallbacks for suspended components while continuing to process suspended components in the background. The server then streams additional HTML chunks as each suspended component resolves, including instructions for the browser to seamlessly replace fallbacks with final content. It works well for: * Pages with mixed data requirements: Some fast, some slow data sources * Improving perceived performance: Show users something quickly while slower parts load * Complex dashboards: Different widgets have different loading times * Handling slow APIs: Prevent slow third-party services from blocking the entire page How Streaming Affects Core Web Vitals * Largest Contentful Paint (LCP): Streaming can improve the perceived LCP. By sending the initial HTML content quickly, including potentially the largest element, the browser can render it sooner. Even if other parts of the page are still loading, the user sees the main content faster. * Interaction to Next Paint (INP): Streaming can contribute to a better INP. When used with React's <Suspense />, interactive elements in the faster-loading parts of the page can become interactive earlier, even while other components are still being streamed in. This allows users to engage with the page sooner. * Cumulative Layout Shift (CLS): Streaming can cause layout shifts as new content streams in. However, when implemented carefully, streaming should not negatively impact CLS. The initially streamed content should establish the main layout, and subsequent streamed chunks should ideally fit within this structure without causing significant reflows or layout shifts. Using placeholders and ensuring dimensions are known can help prevent CLS. Code Examples: 1. Basic Streaming with Suspense: ` 2. Nested Suspense boundaries for more granular control: ` 3. Using Next.js loading.js convention: ` 4. Client Components and Client-Side Rendering Client Components are defined using the React 'use client' directive. They are pre-rendered on the server but then hydrated on the client, enabling interactivity. This is different from pure client-side rendering (CSR), where rendering happens entirely in the browser. In the traditional sense of CSR (where the initial HTML is minimal, and all rendering happens in the browser), Next.js has moved away from this as a default approach but it can still be achievable by using dynamic imports and setting ssr: false. ` Despite the shift toward server rendering, there are valid use cases for CSR: 1. Private dashboards: Where SEO doesn't matter, and you want to reduce server load 2. Heavy interactive applications: Like data visualization tools or complex editors 3. Browser-only APIs: When you need access to browser-specific features like localStorage or WebGL 4. Third-party integrations: Some third-party widgets or libraries that only work in the browser While these are valid use cases, using Client Components is generally preferable to pure CSR in Next.js. Client Components give you the best of both worlds: server-rendered HTML for the initial load (improving SEO and LCP) with client-side interactivity after hydration. Pure CSR should be reserved for specific scenarios where server rendering is impossible or counterproductive. Client components are good for: * Interactive UI elements: Forms, dropdowns, modals, tabs * State-dependent UI: Components that change based on client state * Browser API access: Components that need localStorage, geolocation, etc. * Event-driven interactions: Click handlers, form submissions, animations * Real-time updates: Chat interfaces, live notifications How Client Components Affect Core Web Vitals * Largest Contentful Paint (LCP): Initial HTML includes the server-rendered version of Client Components, so LCP is reasonably fast. Hydration can delay interactivity but doesn't necessarily affect LCP. * Interaction to Next Paint (INP): For Client Components, hydration can cause input delay during page load, and when the page is hydrated, performance depends on the efficiency of event handlers. Also, complex state management can impact responsiveness. * Cumulative Layout Shift (CLS): Client-side data fetching can cause layout shifts as new data arrives. Also, state changes might alter the layout unexpectedly. Using Client Components will require careful implementation to prevent shifts. Code Examples: 1. Basic Client Component: ` 2. Client Component with server data: ` Hybrid Approaches and Composition Patterns In real-world applications, you'll often use a combination of rendering strategies to achieve the best performance. Next.js makes it easy to compose Server and Client Components together. Server Components with Islands of Interactivity One of the most effective patterns is to use Server Components for the majority of your UI and add Client Components only where interactivity is needed. This approach: 1. Minimizes JavaScript sent to the client 2. Provides excellent initial load performance 3. Maintains good interactivity where needed ` Partial Prerendering (Next.js 15) Next.js 15 introduced Partial Prerendering, a new hybrid rendering strategy that combines static and dynamic content in a single route. This allows you to: 1. Statically generate a shell of the page 2. Stream in dynamic, personalized content 3. Get the best of both static and dynamic rendering Note: At the time of this writing, Partial Prerendering is experimental and is not ready for production use. Read more ` Measuring Core Web Vitals in Next.js Understanding the impact of your rendering strategy choices requires measuring Core Web Vitals in real-world conditions. Here are some approaches: 1. Vercel Analytics If you deploy on Vercel, you can use Vercel Analytics to automatically track Core Web Vitals for your production site: ` 2. Web Vitals API You can manually track Core Web Vitals using the web-vitals library: ` 3. Lighthouse and PageSpeed Insights For development and testing, use: * Chrome DevTools Lighthouse tab * PageSpeed Insights * Chrome User Experience Report Making Practical Decisions: Which Rendering Strategy to Choose? Choosing the right rendering strategy depends on your specific requirements. Here's a decision framework: Choose Static Rendering when * Content is the same for all users * Data can be determined at build time * Page doesn't need frequent updates * SEO is critical * You want the best possible performance Choose Dynamic Rendering when * Content is personalized for each user * Data must be fresh on every request * You need access to request-time information * Content changes frequently Choose Streaming when * Page has a mix of fast and slow data requirements * You want to improve perceived performance * Some parts of the page depend on slow APIs * You want to prioritize showing critical UI first Choose Client Components when * UI needs to be interactive * Component relies on browser APIs * UI changes frequently based on user input * You need real-time updates Conclusion Next.js provides a powerful set of rendering strategies that allow you to optimize for both performance and user experience. By understanding how each strategy affects Core Web Vitals, you can make informed decisions about how to build your application. Remember that the best approach is often a hybrid one, combining different rendering strategies based on the specific requirements of each part of your application. Start with Server Components as your default, use Static Rendering where possible, and add Client Components only where interactivity is needed. By following these principles and measuring your Core Web Vitals, you can create Next.js applications that are fast, responsive, and provide an excellent user experience....

May 30, 2025

9 mins

NextJS

Let's innovate together!

We're ready to be your trusted technical partners in your digital innovation journey.

Whether it's modernization or custom software solutions, our team of experts can guide you through best practices and how to build scalable, performant software that lasts.

How to set up screenshot comparison testing with cypress inside an NX workspace

What is snapshot testing?

Install dependencies

Set up configurations

Run the tests inside Docker

Balázs Tápai

You might also like

Harnessing the Power of Threlte - Building Reactive Three.js Scenes in Svelte

A Deep Dive into SvelteKit's Rendering Techniques

Introducing the express-typeorm-postgres Starter Kit

Next.js Rendering Strategies and how they affect core web vitals

Let's innovate together!

You might also like

Harnessing the Power of Threlte - Building Reactive Three.js Scenes in Svelte

A Deep Dive into SvelteKit's Rendering Techniques

Introducing the express-typeorm-postgres Starter Kit

Next.js Rendering Strategies and how they affect core web vitals