Forem: Pedro Figueiredo

Interact with Neon APIs using Claude Code through natural language

Pedro Figueiredo — Fri, 29 Aug 2025 15:20:38 +0000

Imagine adjusting your database schema simply by describing the change in plain English. This is possible by combining Claude Code with the Neon MCP Server.

This guide demonstrates how to use Claude Code's command-line interface and Neon's MCP server to perform database migrations in your Neon project.

The Neon MCP Server grants powerful database management capabilities through natural language requests. Always review and authorize actions requested by the LLM before execution. Ensure that only authorized users and applications have access to the Neon MCP Server.

The Neon MCP Server is intended for local development and IDE integrations only. We do not recommend using the Neon MCP Server in production environments. It can execute powerful operations that may lead to accidental or unauthorized changes.

For more information, see MCP security guidance.

Key components

Let's break down the key components in this setup:

Claude Code: Claude Code is Anthropic's official CLI tool that supports Model Context Protocol (MCP) for interfacing with external tools (APIs, databases, etc.)
Neon MCP Server: Neon's MCP server acts as a bridge between MCP clients like Claude Code and Neon's API, letting you work with Neon databases using natural language commands.
Model Context Protocol (MCP): MCP is a lightweight communication standard that allows Claude Code and Neon MCP Server to work together.

Setting up Neon MCP Server in Claude Code

You have two options for connecting Claude Code to the Neon MCP Server:

Remote MCP Server (Preview): Connect to Neon's managed MCP server using OAuth for authentication. This method is more convenient as it eliminates the need to manage API keys in Claude Code. Additionally, you will automatically receive the latest features and improvements as soon as they are released.
Local MCP Server: Run the Neon MCP server locally on your machine, authenticating with a Neon API key.

Prerequisites

Before you begin, ensure you have the following:

Claude Code: Ensure you have Claude Code installed. Visit docs.anthropic.com/en/docs/claude-code for installation instructions.
Neon API Key (for Local MCP server): After signing up, get your Neon API Key from the Neon console. This API key is needed to authenticate your application with Neon. For instructions, see Manage API keys.

Keep your Neon API key secure, and never share it publicly. It provides access to your Neon projects.

Node.js (>= v18) and npm: Ensure Node.js (version 18 or later) and npm are installed. Download them from nodejs.org.

Option 1: Setting up the Remote Hosted Neon MCP Server

Note: By default, the Remote MCP Server connects to your personal Neon account. To connect to an organization's account, you must authenticate with an API key. For more information, see API key-based authentication.

This method uses Neon's managed server and OAuth authentication.

Open your terminal.
Add the Neon MCP server to Claude Code with the following command:

   claude mcp add --transport http neon https://mcp.neon.tech/mcp

Start a new session of claude to trigger the OAuth authentication flow:

   claude

You can also trigger authentication with /mcp within Claude Code.

If you prefer to authenticate using a Neon API key, provide the Authorization header to the mcp add command:

claude mcp add --transport http neon https://mcp.neon.tech/mcp \
    --header "Authorization: Bearer <YOUR_NEON_API_KEY>"

Replace <YOUR_NEON_API_KEY> with your actual Neon API key which you obtained from the prerequisites section.

The remote hosted MCP server is in preview due to the new OAuth MCP specification, expect potential changes as we continue to refine the OAuth integration.

Option 2: Setting up the Local Neon MCP Server

This method runs the Neon MCP server locally on your machine, using a Neon API key for authentication.

Open your terminal.
Add the Neon MCP server to Claude Code with the following command, replacing <YOUR_NEON_API_KEY> with your actual Neon API key:

   claude mcp add neon -- npx -y @neondatabase/mcp-server-neon start "<YOUR_NEON_API_KEY>"

Replace <YOUR_NEON_API_KEY> with your actual Neon API key which you obtained from the prerequisites section.

Start a new Claude Code session with the claude command and start using the Neon MCP server:

   claude

You've now configured the Neon MCP Server in Claude Code and can manage your Neon Postgres databases using AI.

Verification

Now that you have the Neon MCP server set up either remotely or locally, you can verify the connection and test the available tools.

Start Claude Code:

   claude

Type /mcp to see the available MCP servers and tools.
Try out a Neon MCP Server tool by typing a query like List my Neon projects to see your projects and verify the connection.

Supported Actions (Tools)

The Neon MCP Server provides the following actions, which are exposed as "tools" to MCP Clients. You can use these tools to interact with your Neon projects and databases using natural language commands.

Project management:
list_projects: Retrieves a list of your Neon projects, providing a summary of each project associated with your Neon account. Supports limiting the number of projects returned (default: 10).
describe_project: Fetches detailed information about a specific Neon project, including its ID, name, and associated branches and databases.
create_project: Creates a new Neon project in your Neon account. A project acts as a container for branches, databases, roles, and computes.
delete_project: Deletes an existing Neon project and all its associated resources.
list_organizations: Lists all organizations that the current user has access to. Optionally filter by organization name or ID using the search parameter.

Branch management:
create_branch: Creates a new branch within a specified Neon project. Leverages Neon's branching feature for development, testing, or migrations.
delete_branch: Deletes an existing branch from a Neon project.
describe_branch: Retrieves details about a specific branch, such as its name, ID, and parent branch.
list_branch_computes: Lists compute endpoints for a project or specific branch, including compute ID, type, size, and autoscaling information.

SQL query execution:
get_connection_string: Returns your database connection string.
run_sql: Executes a single SQL query against a specified Neon database. Supports both read and write operations.
run_sql_transaction: Executes a series of SQL queries within a single transaction against a Neon database.
get_database_tables: Lists all tables within a specified Neon database.
describe_table_schema: Retrieves the schema definition of a specific table, detailing columns, data types, and constraints.
list_slow_queries: Identifies performance bottlenecks by finding the slowest queries in a database. Requires the pg_stat_statements extension.

Database migrations (schema changes):
prepare_database_migration: Initiates a database migration process. Critically, it creates a temporary branch to apply and test the migration safely before affecting the main branch.
complete_database_migration: Finalizes and applies a prepared database migration to the main branch. This action merges changes from the temporary migration branch and cleans up temporary resources.

Query performance tuning:
explain_sql_statement: Analyzes a SQL query and returns detailed execution plan information to help understand query performance.
prepare_query_tuning: Identifies potential performance issues in a SQL query and suggests optimizations. Creates a temporary branch for testing improvements.
complete_query_tuning: Finalizes and applies query optimizations after testing. Merges changes from the temporary tuning branch to the main branch.

Neon Auth:
provision_neon_auth: Provisions Neon Auth for a Neon project. Sets up authentication infrastructure by creating an integration with Stack Auth (@stackframe/stack).
These actions enable any MCP client like Claude Code to interact with various functionalities of the Neon platform via the Neon API. Certain tools, especially database migration ones, are tailored for AI agent and LLM usage, leveraging Neon's branching for safe preview and commit.

These actions enable any MCP client like Claude Code to interact with various functionalities of the Neon platform via the Neon API. Certain tools, especially database migration ones, are tailored for AI agent and LLM usage, leveraging Neon's branching for safe preview and commit.

Development Workflow: Adding a Column with Claude Code and Neon MCP

Let's walk through a typical development scenario: Quickly adding a column for prototyping using natural language within Claude Code. The following chat log demonstrates a real interaction with Claude Code and the Neon MCP server.

Scenario: During development, you decide to track timestamps for entries in your playing_with_neon table. You want to quickly add a created_at column.

For your security, review the tool's purpose before permitting the operation to proceed. Remember that LLMs can sometimes produce unexpected results, so careful monitoring is always recommended.

Here's the conversation log between the user and Claude Code:

User: In my neon project id: round-salad-44063611 list all the tables
Claude Code: I'll help you list all the tables in your Neon project. I'll use the default database name 'neondb' since none was specified.
> Called MCP Tool (get_database_tables)
> I found one table in your database:
> playing_with_neon (in the public schema)
> Would you like to see more details about this table's structure or perform any other operations with it?

User: Can you show me first 5 rows?
Claude Code: I'll query the first 5 rows from the playing_with_neon table.
> Called MCP Tool (run_sql)
> Here are the first 5 rows from the table. The table has three columns:
> id (sequential numbers)
> name (string values)
> value (decimal numbers)
> Would you like to perform any other operations with this data?

User: can you add a created_at column?
Claude Code: I'll help you add a created_at column to the playing_with_neon table. I'll set it up with a timestamp data type and set it to automatically record the creation time of new rows.
> Called MCP Tool (prepare_database_migration)
> Let me verify the change in the temporary branch to make sure it was applied correctly.
> Called MCP Tool (run_sql)
> I've added the created_at column to the playing_with_neon table in a temporary branch. Would you like to commit this migration to the production branch?
> Migration Details:
> Migration ID: a65babcd-d1cc-401f-89b5-762570570102
> Temporary Branch Name: br-silent-cherry-a1eqrl6i
> Temporary Branch ID: br-silent-cherry-a1eqrl6i
> Migration Result: Success
> Please let me know if you'd like to proceed with applying this change to the production branch.

User: yeah do it
Claude Code: I'll complete the migration and apply the changes to the production branch.
> Called MCP Tool (complete_database_migration)
> The migration has been successfully completed! The created_at column has been added to your table in the production branch, and the temporary branch has been cleaned up.

Key takeaways:

Natural language interaction: You can use simple, conversational English to interact with your database.
Step-by-step guidance: Claude Code confirms each step and provides details like branch names and migration IDs.
MCP Tools in Action: The underlying MCP tools (get_database_tables, run_sql, prepare_database_migration, complete_database_migration) illustrate the automated process.
Branching for safety: The agent automatically creates a temporary branch for schema changes. The user will be prompted to confirm the migration before applying it to the production branch.

You can verify the changes in your Neon Console or by querying the database directly.

Bonus: Creating a project and branch

Beyond schema changes, you can also manage your Neon projects and branches directly within Claude Code using natural language commands. This can be useful for quickly setting up a new development or test environment.

Creating a new project

Let's say you want to create a new Neon project named "my-new-project". You can simply tell Claude Code:

User: Create a Neon project named "my-new-project"
Claude Code: I'll help you create a new Neon project with the specified name.
> Called MCP Tool (create_project)
> Great! I've created a new Neon project for you with the name "my-new-project". Here are the important details:
> Project ID: orange-dawn-33739962
> Default branch: main
> Default database: neondb
> The project is ready to use. You can start creating tables and working with your database right away.

Claude Code will then use the create_project MCP tool to initiate the project creation. It will provide you with a project ID and name.

Creating a New Branch

Once you have a project, you can easily create new branches for development or experimentation. For example, to create a branch named "feature-x" in your "my-new-project" project:

User: Create a branch named "feature-x"
Claude Code: Perfect! I've created a new branch named "feature-x". Here are the details:
> Branch ID: br-cold-mountain-a523ka2w
> Branch name: feature-x
> Parent branch ID: br-odd-pine-a5y53krm
> The branch has been created successfully and is ready for use.

Claude Code will use the create_branch MCP tool to create the branch and provide you with the branch name and ID. Notice how we don't need to specify the project ID, as Claude Code remembers the active project context.

Conclusion

Claude Code combined with the Neon MCP Server, whether using the Remote Hosted (Preview) option or the Local Server setup, lets you use natural language to interact with your database and take advantage of Neon's branching capabilities for fast iteration. This approach is ideal for quickly testing database ideas and making schema changes during development.

Resources

Fixing TypeScript Dates

Pedro Figueiredo — Sun, 14 Jan 2024 18:27:57 +0000

Dates formats and timezones have for many years and probably for many more to come, been the nightmare of many developers and also the root of a lot of bugs in very different systems.

Dates in TypeScript

By typing a variable as Date in TypeScript you are defining that:

1- it is an object
2- it represents a Date
3- it has access to a lot of date-related methods- e.g. getDate

However, there are still two very important pieces of information that aren't defined in any way by the type system:

1 - What's the date's timezone?
2 - What's the date's format?

Narrowing dates information

Unfortunately, for the timezone, there isn't much that TypeScript can do for us, because it would be "impossible" for a static analysis tool to understand from a given "date string", which timezone it represents, at least without any further info or complex runtime validation.

However, for a date's format, TypeScript can be very helpful and provide just enough narrowing for us to validate if a "date string" represents a given format, all within the type system! Here is a brief example of how we could define a type for the European date string format:



// European DD/MM/YYYY
type EuropeanDate = `${number}${number}/${number}${number}/${number}${number}${number}${number}`;

const europeanDate: EuropeanDate = "20/10/2024"; ✅

Eventually, this may lead to some false positives, like the "MM/DD/YYYY" (American format), but type-wise, those formats are the same, so there isn't much we can do there.

Dates in Data Contracts

A data contract outlines how data can get exchanged between two parties. atlan

Data contracts are in it's essence, a way to communicate what data a given resource is going to deliver and expects to receive.

In the TypeScript ecosystem, having these contracts well-defined (or even auto-generated) is a must, as a lot of times clients rely on them to make requests and manipulate/present the response data.

But date types are usually a bit different from the rest of the data, due to their sensibility, they usually need to be passed around in the same format, but how can we know in which format, if the contract is defined like this:



type CreateTask = {
  name: string;
  // date in ISO format (is it?)
  dueDate: string;
}

type GetTask = {
  name: string;
  // date in ISO format
  dueDate: string;
}

As you can see above, it's very common that we add comments pointing out what's the actual date format, due to the absence of a better alternative.

Enforcing a date format

The most common date format used in IT systems is probably the ISO 8601, it is a standard date and time representation that ensures consistency and is easily sortable, also, it has very good support across different programming languages and systems.

Basic format: YYYY-MM-DD
Extended format: YYYY-MM-DDTHH:MM:SS

This means that ideally, our data contracts would also have all the date fields typed as ISO somehow.



type GetTask = {
  name: string;
  // date in the ISO format!
  dueDate: TDateISO;
}

Defining the `TDateISO` type

The 1st step to have our date field typed properly, is obviously to define a TypeScript type that represents the ISO 8601 date string format.

This type was extracted from this gist.



type TYear         = `${number}${number}${number}${number}`;
type TMonth        = `${number}${number}`;
type TDay          = `${number}${number}`;
type THours        = `${number}${number}`;
type TMinutes      = `${number}${number}`;
type TSeconds      = `${number}${number}`;
type TMilliseconds = `${number}${number}${number}`;

/**
 * Represent a string like `2021-01-08`
 */
type TDateISODate = `${TYear}-${TMonth}-${TDay}`;

/**
 * Represent a string like `14:42:34.678`
 */
type TDateISOTime = `${THours}:${TMinutes}:${TSeconds}.${TMilliseconds}`;

/**
 * Represent a string like `2021-01-08T14:42:34.678Z` (format: ISO 8601).
 *
 * It is not possible to type more precisely (list every possible values for months, hours etc) as
 * it would result in a warning from TypeScript:
 *   "Expression produces a union type that is too complex to represent. ts(2590)
 */
type TDateISO = `${TDateISODate}T${TDateISOTime}Z`;

As stated in the comments in the code block, this isn't bulletproof, but as of right now, it is as far as we can go, type-wise, and it's probably good enough for a data contract where you control both the frontend and the backend of the systems communication.

Overriding native `toISOString`

As you can see above, the native JS Date prototype toISOString() isn't ready for this new type that we just created and in fact, it just returns a simple string. So, we must somehow override its return type.

Luckily for us, the Date type is defined in an interface, and interfaces can be "merged" with other interfaces due to declaration merging - meaning that we can create a new interface with the same name, and modify the existing types (within certain limits).



// add this to any TS module (file with exports/imports)
interface Date {
  /**
   * Give a more precise return type to the method `toISOString()`:
   * https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString
   */
  toISOString(): TDateISO;
}

Once that's done, anytime we use the native toISOString, will result in the TDateISO that we created in the previous step. 👇

Summary

1- Standardize all the data contract's dates' format
2- Setup a new TS type that can represent that date format
3- Change the dates in the contracts to the new type
4- Narrow the return type of the native Date functions, if it applies to your system's date format

Conclusion

Dates don't have an easy time in the TypeScript ecosystem, due to so many different variations in formats and timezones, it is still pretty much impossible to have full type safety.

However, for date formats, it is already possible to narrow down the types enough, to get a much better and safer Developer Experience.

Make sure to follow me on twitter if you want to read about TypeScript best practices or just web development in general!

Splitting and Caching React Chunks

Pedro Figueiredo — Sat, 30 Dec 2023 16:42:41 +0000

There are only two hard things in Computer Science: cache invalidation and naming things. - Phil Karlton

Caching is still today one of the hardest things to get right. Nevertheless, it stands as an indispensable element for optimizing performance in any system, essential for unlocking its full potential.

For a SPA (Single Page Application), the perfect caching strategy would be to split our code into 2 different categories: common chunks and route chunks. That way, we could in theory only download the necessary JS/CSS code for a given route and re-use all the common (already cached), parts of the code.

Code Chunks

A "chunk," as defined by Webpack, refers to the distinct components that collectively form a bundle. In the context of Webpack, a bundle serves as the entry point for organizing and encapsulating these individual chunks of code.

Another property that distinguishes chunks is their independence, meaning that every one of them will be downloaded as a different source - e.g. a bundle with 4 chunks will lead to 4 HTTP requests.

Code Splitting

To deliver the best experience in a web application, it is crucial that the browser only downloads and executes the bare minimum JS/CSS that's needed for a given page/route and that it progressively downloads and executes the rest as needed.

To achieve these sorts of optimizations, code bundlers (e.g. Webpack, Rollup...) tend to provide a way to split chunks per route. This means that for each route visited, there will be a preset of chunks that will be downloaded by the browser, as the user navigates through the different pages/routes.

Above we can see a very simplistic view of how navigating into the /page1 route would lead to only downloading the necessary parts - common-chunk.js and page1-chunk.js.

Identifying the common code

For the most part, bundlers do a "good enough" work by creating multiple independent chunks that can be re-used across a web app, so that users only download the bare minimum that's needed for a given page. Take a quick peek at Webpack docs below on when it creates a new chunk automatically:



Webpack will automatically split chunks based on these conditions:

- New chunk can be shared OR modules are from the node_modules folder
- New chunk would be bigger than 20kb (before min+gz)
- Maximum number of parallel requests when loading chunks on demand would be lower or equal to 30
- Maximum number of parallel requests at initial page load would be lower or equal to 30

When trying to fulfill the last two conditions, bigger chunks are preferred.

However, we can probably do better with very little work, just by looking at our app and understanding which parts of the code we should extract into independent chunks.

While there is potential to take loads of time to optimize this process, we should probably stick to the ones that will have the most impact on our bundle size and that will be used in most routes, and these usually fall under one of the following categories:

[related vendors] react, react-dom and react-router-dom
[globally used vendors] lodash, css-in-js lib, etc...
[global styles] CSS Reset files, global styles files, etc...

Extracting common parts into chunks

Once we have identified all the common parts of code we want to extract into independent chunks, it's usually very straightforward to actually set this up in whatever bundler you are using.

Here is an example of how we could create a new chunk for all the react related vendors using webpack:



const path = require('path');

module.exports = {
 ...,
  optimization: {
    splitChunks: {
      cacheGroups: {
        reactVendor: {
          test: /[\\/]node_modules[\\/](react|react-dom|react-router-dom)[\\/]/,
          name: 'vendor-react',
          chunks: 'all',
        },
      },
    },
  },
};

This Webpack config uses splitChunks combined with cacheGroups to create specific code chunks that pass the given test regex:



reactVendor: {
  test: /[\\/]node_modules[\\/](react|react-dom|react-router-dom)[\\/]/,
  name: 'vendor-react',
  chunks: 'all',
},

After we apply this change to the config, Webpack will generate a new chunk that will include any code that comes from react, react-dom, or react-router-dom, with the name reactVendor.js.

The last step to get this working, is to include this newly produced asset in our HTML file:



<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>My App</title>
    <script src="./vendor-react.js"></script>
  </head>
  <body>
    <script src="./app.js"></script>
  </body>
</html>

Since we need React to run our application, it's better to include it on the head tag, so it's picked up faster by the browser.

However, to fully leverage this new chunk, it's crucial to configure caching, ensuring it is downloaded only once and subsequently "reused" across all page navigations.

Caching Static Assets (Chunks)

To efficiently cache static assets, there are certain aspects we need to take into consideration:

what's the best strategy
when to invalidate the cache
how to invalidate the cache

In my opinion, the best way to cache static assets is a combination of CDN distribution with cache busting, so that's what we will discuss below.

CDN Distribuition

A content delivery network (CDN) is a geographically distributed group of servers that caches content close to end users. A CDN allows for the quick transfer of assets needed for loading Internet content, including HTML pages, JavaScript files, stylesheets, images, and videos. - Cloudflare

The CDN will be 1st opportunity for caching, since that's the system that we will be hitting when visiting a web app for the first time. Bear in mind that it will not, prevent the consumers of a web app from downloading the assets (that's the browser's work), but it will make the load time much faster by placing the static assets closer to the user's device, at least, once they are cached.

Enabling cache for CDNs is usually well-defined within their docs, but the most common practice is setting the Cache-Control header to public and max-age with a value greater than 0, like so:



Cache-Control: max-age=31536000,immutable

The best/simpler practice in this regard would be to add the Cache-Control header to every single asset BUT the ones that are NOT created by the bundler, meaning: .html, .png, .gif... And that's just because they don't pass by a bundling process that allows us to change their name depending on the content.

CDN Cache Invalidation

Invalidating the cache is a very sensible process and as such, it should be as straightforward as possible, so that we can minimize errors, such as delivering outdated assets.

The simplest and most effective strategy for this is to invalidate the cache every time we make a make a new deployment, for all the assets that are not part of our bundling process, such as:

.html
.png
.jpg
.gif
...

And this is simply because even if these assets change, they can still keep the same name and we don't really have a way to signalize the CDN if they are outdated or not.

Cache Busting

Cache busting is a technique used by web developers to force the browser to load the most recent version of a file, rather than a previously cached version. - keyCDN

We still need to somehow signalize both the CDN and the Browser if we should get a new asset or re-use the cached one. And the best way to do that is through cache busting.

Cache busting can be applied with different strategies, such as:



// File name versioning
"index.v2.js"

// File path versioning
"/v2/index.js"

// Query params versioning
"index.js?v=2"

// File content hashing
"[name].[contenthash].js"

File content hashing

From my experience, content hashing is the best cache busting strategy for 3 reasons:

1- we don't rely on past data (like in versioning)
2- we can still use cached assets even after new deployments
3- cache busting is done automatically by having differently named files when their content changes

In Webpack, to generate the chunk names using their content hashes, we can change the output format like so:



// webpack config
module.exports = {
  entry: {
    app: './src/app.js',
  },
  output: {
    // entry bundle chunks names
    filename: '[name].[contenthash].js', // 🆕
    // non-initial chunk names
    chunkFilename: '[name].[contenthash].bundle.js', // 🆕
    path: path.resolve(__dirname, 'dist/app'),
    // removes old bundles from the directory
    clean: true, // 🆕
  },
  ...
};

Once we build our web app with such configuration, we will have something similar to this:



📁 dist/

 ├── 📄 index.html

 ├── 📄 app.575d644de9307ca8621d.js

 └── 📄 vendor-react.7c8b137d61bff5cad6e7.bundle.js

Summary

1- Extract common parts of code into their own chunks;
2- Distribute your web app through a CDN;
3- Invalidate non-bundled assets on deployment;
4- Setup a caching strategy through cache busting;

Sources

Make sure to take a look at these sources if you wanna have a more in-depth understanding of caching and code splitting:

Conclusion

Distributing cached assets is the best way to spare the clients from downloading unnecessary code and having a much faster loading time.

One of the best ways to do it is by distributing your web app through a CDN and setting up a strategy that allows for invalidating new assets when their content changes.

Make sure to follow me on twitter if you want to read about TypeScript best practices or just web development in general!

Making lodash tree-shakable

Pedro Figueiredo — Sun, 19 Nov 2023 19:23:30 +0000

TL;DR

1- Replace `lodash` with `lodash-es`
2- Ditch default imports
3- Prefer namespace imports - import * as _ from "lodash-es"
4- Setup a linter rule to not allow this happen again
5- See great bundle size improvements 😎

Lodash

Lodash is a JS utility library that delivers small functions capable of easing the way we work with arrays, numbers, objects, strings, etc.

isEmpty
lowerCase
concat
defer
...

And although it's about 11 years old, lodash is still today, the most "depended-upon" package, according to the npm registry. So it's very likely that you are using it directly or indirectly through one of your dependencies.

CommonJS

When lodash was first introduced in 2011, CommonJS was the common standard to write JS modules, however, that standard was mainly intended to be used in server-side applications and never to reach the browser.

But in 2023, the lodash library is still being widely used in web applications, and of course, it's still written in the CommonJS format.

Tree Shaking in CommonJS

Tree shaking is a process in modern JavaScript bundlers that eliminates unused code during the build process, resulting in smaller and more optimized bundles.

Because CommonJS was originally designed with server-side applications in mind, it didn't prioritize a crucial aspect for browser-based environments: the ability to be tree shaken.

This happens because CommonJS allows for highly dynamic imports/exports, that bundlers can't simply pick up and do a fully static analysis on, to understand if certain code should be kept or eliminated in the final bundle.

For more in-depth information on how CommonJS works when it comes to tree shaking, make sure to take a look at this great article.

A Tree-Shakable Alternative

In today's web development, ECMAScript is the go-to standard for writing JS modules and it's being widely adapted not only on the browser but also on node environments.

This standard is much more mature and offers much better support for static analysis and tree shaking due to its more declarative and static nature.

Tree-shaking `lodash`

Now that we have gone through why tree shaking doesn't play well with lodash, let's dive into what we can do we make it tree-shakable.

1- Replacing lodash with lodash-es

Due to the huge amount of benefits of using ESM (ECMAScript Modules), the lodash-es lib was created and it's now the recommended package to be installed if you want to continue to use lodash, it is still the same library, but exported as ES modules.

2- Stop using the default import

Another very common practice that might completely ruin tree shaking, is doing a default import when using lodash or any other lib that exports everything from the default exported variable.

import _ from "lodash-es";

// `_` contains every single lodash's function 
_.add(1,2);
_.isEmpy([]);
_.lowerCase("HEY");

In the example above, although we are only using 3 functions, we are actually importing the whole lib, because the default export is an object that contains all the lib's utilities.

3- Use namespace imports

Namespace imports are a way to import every single exported member from a module individually.

import * as _ from "lodash-es";

// `_` contains every single lodash's function 
_.add(1,2);
_.isEmpy([]);
_.lowerCase("HEY");

The difference between this and the default import, is that we are importing add, isEmpty and lowerCase individually and as such, every other import that isn't used will be removed at build time.

Of course, you could also import each utility individually, but because of how similar these function names are to the ones provided by native JS, I highly recommend that you keep the _ prefix when using lodash.

import { some } from "lodash-es";

// makes it harder to understand which one is each ❌
some([null, 0, 'yes', false], Boolean);
[null, 0, 'yes', false].some(Boolean);

// ------------------------------------------------

import * as _ from "lodash-es";

// makes it very easy to understand which one is each ✅
_.some([null, 0, 'yes', false], Boolean);
[null, 0, 'yes', false].some(Boolean);

Bonus tip

To safeguard against unintentional slip-ups, such as default imports that can bloat your app's bundle size, I strongly recommend incorporating an ESLint rule to NOT allow using the default import of lodash-es.

// eslintrc.js
module.exports = {
    rules: {
        "no-restricted-syntax": [
            "error",
            {
                message:
                    "Do not import default from lodash-es. Use a namespace import (* as) instead.",
                selector:
                    'ImportDeclaration[source.value="lodash-es"] ImportDefaultSpecifier',
            },      
        ],
    },
};

Summary

1- Avoid using CommonJS libraries in browser-based applications
2- Be mindful when using default imports and prefer namespace imports
3- Avoid these common pitfalls with linter rules

Conclusion

This approach is not exclusive to lodash, and it can actually be applied to a variety of packages, particularly those that are still being exported as CommonJS.

Make sure to follow me on twitter if you want to read about TypeScript best practices or just web development in general!

TypeScript Return Types: Separating Fact from Fiction

Pedro Figueiredo — Mon, 13 Feb 2023 00:21:20 +0000

TypeScript Return Types

This subject has been trending a lot on Twitter lately and there have been a lot of discussions, videos and different views around that topic.

It's a topic that sparks different perspectives based on one's background and approach to coding. Some may prefer to focus on the practical aspect, while others might lean more toward the theoretical side.

Let's just say that in the end, there are no rights or wrongs and it's not something you or I should be spending much time thinking about.

TypeScript Inference

...type inference is used to provide type information when there is no explicit type annotation - TS docs

TypeScript being smart and being able to infer a function's return type without any hints, really is the only reason why this discussion even exists.

This doesn't mean that we should solely rely on TypeScript's type inference, as there are situations where explicitly defining the types is certainly the best approach.

TypeScript Functions

Another reason for this discussion stems from the fact that many developers from various backgrounds, not just frontend and TypeScript, have a habit of defining contracts or interfaces first when coding.

However, the current frontend scene is quite different. It focuses on functional programming with a touch of composability, leading to a lot of small and well-defined functions that can be easily combined to achieve more complex tasks.

Infer by default

If you are building a TS based product, chances are that you have a lot of small and simple functions that are self explanatory like:

getName
getAge
getUser
canRemoveItem
onModalOpen
...

By looking at the names of those functions, you can easily deduce their return type. If the return type is not what you expect, it's likely not the type that needs to be changed, but rather the function name itself.

This means that by default, a simple and well defined function shouldn't need explicit return types, it should be implicit by its semantics, or in other words, inferred.

Advantages of inferring

Relying on inferred return types not only simplifies the process, but it also brings several key benefits, including:

Development Speed
Avoiding the need to define return types for small functions and reducing the need to revisit them as code grows leads to faster software development with equal quality.
Code Maintainability
Defining return types add extra code that must be maintained, potentially leading to adjustments for small functions with well-defined boundaries, resulting in unnecessary complexity.
Source of Truth
When you rely on the inferred return type, the source of truth will always lay on your code's implementation, whatever you return, will always stick as the return type.

The same, however, isn't true if you implicitly define it, as you can "easily" override the correct return type by mistake:

type Animal = {
    name: string,
    age: number,
}

function getAnimal(): Animal{
    const dog = {
        name: "Joey",
        age: 7,

// TS accepts this property, but Animal doesn't have it ❌
        breed: "Boxer"
    }

    return dog;
}

When to use Return Types

If by default we should allow inference to do the dirty work, then, in which situations should we be explicitly defining a function's return types?

There are actually some situations where it's useful to define it and more than not, it is related to the function's own complexity.

1. Narrowing return types

type SuccessAction<T> = {
    type: "SUCCESS_FETCH";
    payload: T;
};

function successAction<T>(payload: T): SuccessAction<T> {
    return {
        type: "SUCCESS_FETCH",
        payload,
    };
}

One common scenario, is when you define "action creator" functions that return a store's action (Redux or not).

There are actually 2 reasons to define the return type here:

If we don't define it, the type property will be string instead of the literal "SUCCESS_FETCH".
It makes way more sense to see SuccessAction as the return type, instead of just a "random" object.

2. Multiple code branches

It's very common for functions to get big and complex and with a lot of code branches that may lead to different return types.

If that's the case, you will NOT want to see a bunch of unions of different return types on your screen.

type Action = "CLOSE_TODO" | "CREATE_TODO";

// This leads to a pretty loose union of return types ❌
function handleTodo(action: Action) {
    switch (action) {
        case "CLOSE_TODO":
            return {
                status: "closed" as const,
                closedTimestamp: Date.now()
            }
        case "CREATE_TODO":
            return {
                status: "new" as const,
                createTimeStamp: Date.now()
            }
    }
}

Looking at the sample of code above, it's easy to understand that the more code branches, the more possibilities there are to return the wrong thing, even more if the return type changes depending on some condition (like this case).

// with defined return type ✅
type TodoSate = {
    status: "closed",
    closedTimestamp: number,
} | {
    status: "new",
    createTimeStamp: number,
};

type Action = "CLOSE_TODO" | "CREATE_TODO";

function handleTodo(action: Action): TodoSate  {
    switch (action) {
        case "CLOSE_TODO":
            return {
                status: "closed" as const,
                closedTimestamp: Date.now()
            }
        case "CREATE_TODO":
            return {
                status: "new" as const,
                createTimeStamp: Date.now()
            }
    }
}

Defining the return type in these sorts of scenarios, can have major advantages such as:

1- Not allowing impossible states, like having the status open and the closedTimestamp defined.
2- Not allowing typos in any of the returned objects.
3- It's much more scalable as the functions grow in size/complexity.

3. Library's code

For library's code, however, the story is much different when it comes to return types. The main rule here is, for every function that is being publicly exposed, you should define the return type and the reasons are pretty simple:

1- Consumers should be able to import and utilize the return type of a function in order to effectively reuse and compose the library's functionalities.
2- Having a well-defined return type "name" saves developers time and eliminates the need to constantly refer to type definition files.

Conclusion

When using TypeScript for development, it's best to rely on inferred return types and only define them in specific cases. This approach leads to faster development and reduces the risk of errors, improving both speed and reliability of your code.

Make sure to follow me on twitter if you want to read about TypeScript best practices or just web development in general!

2 NEW killer features coming to TypeScript

Pedro Figueiredo — Thu, 05 May 2022 23:16:13 +0000

TypeScript 4.7

This upcoming TypeScript version will bring a lot of new features and improvements to the language, but there are 2 in particular that I found especially interesting:

1- Instatiation Expressions

2- extends Constraints on infer Type Variables

New features value

If you are anything like me and enjoy creating complex type definitions that provide great levels of Developer Experience to you and your co-workers, then you should absolutely be on top of these new features, as they will ease the way you write those type definitions, by A LOT.

Reduce your types complexity;
Reduce your types verbosity;
Decrease the amount of workarounds;

Instantiation Expressions

For anyone that has written more than a handful of generic functions, this new feature is probably something that could have saved you from writing "crappy" JS workarounds to get some types going.

Instantiation Expressions will allow us to get a generic type, without the "instantiation" part 🤯

Before 4.7:



type Dog = {
  name: string
  isGoodBoy: boolean;
}

type Cat = {
  name: string
}

function getBigPet<T>(pet: T){
    return {...pet, big: true}
}

// 1- Need to have a typed param to pass 👎
const dog: Dog = {name: "Jake", isGoodBoy: true}

// 2- Need to create an arrow function 👎
const getBigDog = () => getBigPet(dog);

Before this upcoming version, there was really no way to leverage a generic function's type, which led many of us to create workarounds by writing unnecessary JS code. ❌

After 4.7



type Dog = {
  name: string
  isGoodBoy: boolean;
}

type Cat = {
  name: string
}

function getBigPet<T>(pet: T){
    return {...pet, big: true}
}

// Can "instantiate" on the fly ✅
const getBigDog = getBigPet<Dog>;

// No need to bring in any extra types ✅
type BigCat = ReturnType<typeof getBigPet<Cat>>

So, what Instantiation Expressions bring to the table, is the simplicity with which one can retrieve a generic function's type without any sort of workarounds or creating any extra JS code.

PROS

No need to write JS code just for the sake of typing;
The types API gets simplified;
Leveraging function's ReturnType just became a first-class citizen;

`extends` Constraints on `infer` Type Variables

This new feature is something that will help anyone to write way less verbose types when depending on inferred type constraints.

It basically acts as an early return statement that we (developers), many times use in languages like JavaScript to immediately move away to the "false" logical path, when some conditional is met.

Before 4.7



// A type that returns the First and Last elements of the Number type 

// 😔😔😔 This feels overwhelming...
type FirstAndLastNumber<T extends any[]> = T extends [
  infer Head,
  ...any,
  infer Tail
]
  ? Head extends number
    ? Tail extends number
      ? [Head, Tail]
      : never
    : never
  : never;

Before this upcoming feature, there was no way to do an "early check" on the inferred types, and because of that, we ended up creating very verbose and "scary" types. ❌

After 4.7



// The "same" type as before 🤯🤯🤯
type FirstAndLastNumber<T extends any[]> = T extends [

// 1- Add the extends constraint here
  infer Head extends number,
  ...any,

// 2- Add the extends constraint here
  infer Tail extends number
] ? [Head, Tail]: never;

extends Constraints on infer Type Variables really simplifies the process of defining types that rely on inferred type variables - more than a syntax change, this feature really takes the mental model of creating types one step closer to the one we use in "real programming".

PROS
1- Cleaner and less verbose types;
2- Lowers the complexity barrier for others to touch this otherwise "monstrosity" type;
3- TypeScript compiler will be faster because it can return earlier;

Conclusion

By taking advantage of TypeScript's 4.7 version new features, you will be able to lower the complexity of type definitions by a lot, making it way easier for anyone to understand and even develop on top of those types.

P.S. You can already try these new features in the TypeScript Playground

Make sure to follow me on twitter if you want to read about TypeScript best practices or just web development in general!

Generics vs Function Overloading vs Union Type Arguments in TypeScript

Pedro Figueiredo — Mon, 25 Apr 2022 14:58:06 +0000

TypeScript Functions

When it comes to writing TypeScript functions, it is possible, that you have experienced this sort of thinking:

This looks kinda weird, should I try this in another way? Maybe function overloading, or perhaps generics would help here. 🤔

And you ended up changing for one of them, without really knowing if it was the right way.

I've been there and have certainly done this countless times — but what if there was a system that could help you solve this little nuance?

That's exactly what I'm presenting here — a system that will allow you to make a good and consistent decision on how you write a TypeScript function.

Union Types



type Pet = {
  name: string;
};

type PetOwner = {
  name: string;
  pet: Pet;
};

function getPetName(petOrOwner: Pet | PetOwner) {
  if ("pet" in petOrOwner) {
    return petOrOwner.pet.name;
  }

  return petOrOwner.name;
}

TypeScript's union types are super useful when it comes to typing anything that can have multiple type definitions.

For functions in particular, it is super useful to type its parameters or return types. And you are perhaps using it more than you knew, because every time you define a argument as optional , it actually becomes type | undefined, meaning it is a union type underneath!

When to use

When it comes to functions, this is pretty much the most basic strategy for typing its parameters. So my advice is to stick to it whenever possible, but it has more restraints than the others strategies and it doesn't work for more complex scenarios.

Use union types when:

1- You are aware of all the possible members of each union type at the moment of the function's declaration;
2- The return type doesn't change depending on the argument's types;



type Pet = {
  name: string;
};

type PetOwner = {
  ownerName: string;
  pet: Pet;
};

// Don't do this - you will return an ambiguous type ❌
function getObject(petOrOwner: Pet | PetOwner): Pet | PetOwner {
  return petOrOwner;
}


// You have no idea which will be the array type ❌
function getFirstElementArray(arr: (string | number)[]): any  {
  return arr[0];
}

Also, when using union types for typing functions, you should most likely not need to type the return type explicitly. That's just because the return type shouldn't change at all for this way of doing things.

Function Overloading



type SingleNamePerson = {
  name: string;
};

type FullNamePerson = {
  name: string;
  surname: string;
};

// Overload signatures
function getPerson(name: string): SingleNamePerson;
function getPerson(name: string, surname: string): FullNamePerson;

// Implementation signature
function getPerson(
  name: string,
  surname?: string
): SingleNamePerson | FullNamePerson {
  if (name && surname) {
    return {
      name,
      surname,
    };
  }

  return {
    name,
  };
}

TypeScript's function overloads is a great way to specify multiple function signatures in a super declarative way, while making each of those have its own type definition, either for the arguments or the return type.

To leverage this way of typing a function all you need to do is the following:

1- Define your functions' possible signatures (the different overloads)



// Overload signatures
function getPerson(name: string): SingleNamePerson;
function getPerson(name: string, surname: string): FullNamePerson;

2- Define your functions implementations - this function's signature must be a union over the other previously created functions, so that it respects every single overload.



// name - required because it is defined in both overloads
// surname - optional, because it is only present in one of the overloads

// return type - SingleNamePerson | FullNamePerson because it can be either one of those

function getPerson(
  name: string,
  surname?: string
): SingleNamePerson | FullNamePerson {
  if (name && surname) {
    return {
      name,
      surname,
    };
  }

  return {
    name,
  };
}

When to use

Function overloading works pretty well with more difficult and dynamic signatures, as it will provide a way to define multiple combinations in a way that is easy to understand.

Use function overloading when:

1- You are aware of all the possible members of each union type at the moment of the function's declaration;
2- The return type changes depending on the argument's types;
3- The return type isn't a direct mapping of the provided parameters;



// Don't do this ❌ - the return type is a direct mapping of the provided argument (use a generic instead)
function getPerson(person: SingleNamePerson): SingleNamePerson;
function getPerson(person: FullNamePerson): FullNamePerson;
function getPerson(person: {
  name: string;
  surname?: string;
}): SingleNamePerson | FullNamePerson {
  const { name, surname } = person;

  if (name && surname) {
    return {
      name,
      surname,
    };
  }

  return {
    name,
  };
}

Generic Functions



type SingleNamePerson = {
  name: string;
};

type FullNamePerson = {
  name: string;
  surname: string;
};

const singleNamePerson: SingleNamePerson = {
  name: "Bob",
};

const fullNamePerson: FullNamePerson = {
  name: "Bob",
  surname: "Smith",
};

function getPerson<PersonT>(arg: PersonT): PersonT {
  return arg;
}

getPerson(singleNamePerson); // Return type => `SingleNamePerson`
getPerson(fullNamePerson); // Return type => `FullNamePerson`

TypeScript's Generic Functions is probably the most versatile way to create a function that is dynamic in some way or another.

It allows you to get full type support on every possible abstraction for a function that deals with very different scenarios (and where you are not fully aware of what may be passed in as an argument ahead of time).

But all these opportunities and versatility come with a cost. As generics seem to fit everywhere, developers tend to overuse them, and believe me, no one wants to edit a function surrounded by overly complex generic types, especially if it was written by another engineer.

When to use

Generic Functions are the only solution you have to solve the common problem between union types and function overloading — the capacity of adding type support when we are not aware of all the possible types beforehand.

Not only that, but Generics are also a great option when the return type of a function is associated with the types of the parameters (even if you are aware of them ahead of time).



// Defining the return type based on the argument's type
function getFirstElement<T>(array: T[]): T {
    return array[0];
}

const a = getFirstElement([1, 2, 3]); // return type => number
const b = getFirstElement(["Hello", "World"]); // return type => string
const c = getFirstElement([true, false]); // return type => boolean

Use generic functions when:
1- You are NOT aware of the argument types beforehand;
2- The return type is a direct mapping (or close to it) of the provided parameters;



type Dog = {

  name: string;

  toy: string;

};

type Cat = {

  name: string;

  furrballs: number;

};

type Turtle = {

  name: string;

  isMainlyAquatic: boolean;

};

// This can get tricky pretty quickly ❌

type GetAnimalReturnType<AnimalT> = AnimalT extends Dog

  ? "canine"

  : AnimalT extends Cat

  ? "feline"

  : "turtle";

// We need to use type assertions - not ideal ❓

function getAnimalType<AnimalT>(animal: AnimalT): GetAnimalReturnType<AnimalT> {

  if ("toy" in animal) {

    return "canine" as GetAnimalReturnType<AnimalT>;

  }

if ("furrballs" in animal) {

    return "feline" as GetAnimalReturnType<AnimalT>;

  }

return "turtle" as GetAnimalReturnType<AnimalT>;

}

Generics vs function overloading

When it comes to choosing between function overloading and generics the line is blurrier and the decision isn't quite clear. As you can observe in the image above, these two feature usage intersects when it comes to typing a function that has known argument types and whose return type depends on those very same arguments.

Which to choose

The answer will depend on the developer's preference, but my opinion is that to keep things simple you should opt for generics instead of function overloading only when this rule applies:

The code that you need to write to define the return type doesn't have more than 1 level of depth of extends expressions.

That's the rule that I use for myself to keep code consistent and easier for others to read.

Conclusion

There are multiple techniques to write dynamic functions in TypeScript and by applying this "mental model", you will be able to define those functions in a more consistent and clean way, while also making usage of each technique for what it was actually intended. 👇

Unions => Use when return type doesn't change;
Function Overloading => Use when you are aware of the argument types and the return type does change depending on the argument types;
Generics => Use when you are not aware of the argument types or the return type is a direct mapping of the argument types.

Make sure to follow me on twitter if you want to read about TypeScript best practices or just web development in general!

The bullet proof useReducer - Typescript (2/2)

Pedro Figueiredo — Wed, 06 Apr 2022 21:21:52 +0000

This blog post takes by granted that you are aware of useReducer logic and the basics regarding TypeScript.

Bringing TypeScript to the table

In the previous blog post we went in full detail on how to leverage React's useReducer, but there is still something missing for it to be fully bullet proof - TypeScript.

Why does it help

When applying TypeScript into useReducer you will not only feel a sense of security, but also, feel a lot more confident to touch code and modify any logic related with the states inside the reducer.

Pros of using TypeScript:

Type safety
Type completion
Makes sure all states are handled
Makes sure an Action sends the correct data

Cons of using TypeScript

Brings a little more complexity
Makes it harder to hack in a new state quickly

From where I see it, the pros overcome the cons by a lot and as such, I strongly advise you to add some sort of typing to your code.

Typing `fetchReducer`

In the last post, we finished with this plain JS reducer:

Typing Actions

To start, we need to type the different possible actions, so that we have type completion depending on what we are dispatching.

1- Define Action



type Action<DataT, ErrorT> ={}

Action object needs to take in two generics, one for the Data type and one of the Error type.

2- Define FETCH



{ type: "FETCH" }

For FETCH we really only need to define the type's property type, which is a string literal and nothing more.

3- Define RESOLVE



{ type: "RESOLVE", data: DataT }

When we dispatch RESOLVE it means that the fetch was successful and we already have the data - this action ensures that when we do dispatch({type: "RESOLVE"}) there is a type error for not passing the data.

4- Define REJECT



{ type: "REJECT", error: ErrorT }

REJECT acts pretty much as the success action, meaning, that when we dispatch this action, TypeScript will make us pass an error along.

5- Union of actions



type Action<DataT, ErrorT> =
  | { type: "FETCH" }
  | { type: "RESOLVE"; data: DataT }
  | { type: "REJECT"; error: ErrorT };

Our action final type is just an union of all our defined actions, meaning, it can take any of those forms.

Typing States

In order to add more strictness to our reducer, each one of the states should have their own type definition.

All of these states must have the same properties, status, data and error, but for each one of the states, these properties will have their own type definitions, depending on the situation.

1- Typing iddle



type IddleState<DataT> = {
  status: "idle";
  data: Nullable<DataT>;
  error: null;
};

The iddle state takes the DataT generic, so that it allows the reducer to start with initial data. Everything else is pretty standard for all the other reducer states.

2- Typing loading



type LoadingState<DataT, ErrorT> = {
  status: "loading";
  data: Nullable<DataT>;
  error: Nullable<ErrorT>;
};

The loading state needs to take both DataT and ErrorT generics, as it depends too much on the implementation details if we wanna show or not errors while fetching new data.

3- Typing success



type SucessState<DataT> = {
  status: "success";
  data: DataT;
  error: null;
};

The success state only needs the DataT generic and we can already define the error property can be nothing but null, this way, we protect our selves to set errors while in the success state (impossible state)!

4- Typing failure



type FailureState<ErrorT> = {
  status: "failure";
  data: null;
  error: ErrorT;
};

The failure state behaves pretty much like the success one, but in the opposite direction, by setting the error needs a value and that the data must be of the null type.

5- Union of States



type State<DataT, ErrorT> =
  | IddleState<DataT>
  | LoadingState<DataT, ErrorT>
  | SucessState<DataT>
  | FailureState<ErrorT>;

Just like our Action type, State is also just an union of all the possible states that our reducer can return

Typing reducer function

Now that we have all our states and actions properly typed, it's just a matter of adding those to fetchReducer function it self.

1- Adding generics to the function



function fetchReducer<DataT, ErrorT = string>(
    currentState,
    action
  ){
...
}

We defined ErrorT as an optional generic by defining it as string by default.

2-Typing the arguments and the return type



function fetchReducer<DataT, ErrorT = string>(
    currentState: State<DataT, ErrorT>,
    action: Action<DataT, ErrorT>
  ): State<DataT, ErrorT> {
...
}

We just need to take our existing Action and State defined types, and add them to the respective parameters.

For the return type, it was also just a matter of defining that this reducer, can only return any of the states that is inside the State union type.

Typing `useFetchReducer`

Although the reducer function is already properly typed, we still need to add typing to our custom useReducer hook.

1- Passing the generics to the useFetchReducer



// added the generics here
function useFetchReducer<DataT, ErrorT = string>(
  initialData
){

// removed them from the reducer
  function fetchReducer(
    state: State<DataT, ErrorT>,
    event: Event<DataT, ErrorT>
  )
}

By providing generics to the useFetchReducer hook, we don't need to have them on the reducer's signature anymore, as we can use the ones provided above and keep things consistent.

2-Typing initialData argument



function useFetchReducer<DataT, ErrorT = string>(
  initialData: Nullable<DataT> = null
): [State<DataT, ErrorT>, React.Dispatch<Action<DataT, ErrorT>>] {...}

As far as initalData goes, if you wanted to pass in anything, it would have to be the same type that you defined your generic previously.

3-Typing initialState constant



  const initialState: IddleState<DataT> = {
    status: "idle",
    data: initialData,
    error: null,
  };

We should use the IddleState type for the initialState constant, this way, if we decide to change it, TypeScript will make sure they are in sync.

The final type



import { useReducer } from "react";

type Nullable<T> = T | null | undefined;

type IddleState<DataT> = {
  status: "idle";
  data: Nullable<DataT>;
  error: null;
};

type LoadingState<DataT, ErrorT> = {
  status: "loading";
  data: Nullable<DataT>;
  error: Nullable<ErrorT>;
};

type SucessState<DataT> = {
  status: "success";
  data: DataT;
  error: null;
};

type FailureState<ErrorT> = {
  status: "failure";
  data: null;
  error: ErrorT;
};

type State<DataT, ErrorT> =
  | IddleState<DataT>
  | LoadingState<DataT, ErrorT>
  | SucessState<DataT>
  | FailureState<ErrorT>;

type Event<DataT, ErrorT> =
  | { type: "FETCH" }
  | { type: "RESOLVE"; data: DataT }
  | { type: "REJECT"; error: ErrorT };

function useFetchReducer<DataT, ErrorT = string>(
  initialData: Nullable<DataT> = null
) {
  const initialState: IddleState<DataT> = {
    status: "idle",
    data: initialData,
    error: null,
  };

  function fetchReducer(
    state: State<DataT, ErrorT>,
    event: Event<DataT, ErrorT>
  ): State<DataT, ErrorT> {
    switch (event.type) {
      case "FETCH":
        return {
          ...state,
          status: "loading",
        };
      case "RESOLVE":
        return {
          status: "success",
          data: event.data,
          error: null
        };
      case "REJECT":
        return {
          status: "failure",
          data: null,
          error: event.error,
        };
      default:
        return state;
    }
  }

  return useReducer(fetchReducer, initialState);
}

After all this typing, we should be pretty safe when trying to access any reducer's state or even when dispatching actions.

Dispatching Actions

As you can perceive from this GIF, TypeScript doesn't allow us to pass in incorrect Actions into the dispatcher function

Accessing reducer's state

If you look closely, you will notice that TypeScript can infer what's the data and error types by the current state.

This feature it's called Discriminating Unions and it works by having a Discriminator property in each one of the union types, that can help TypeScript narrow down which is the current state - in our case it is the status, which is unique for each of union types.

Conclusion

By using TypeScript in conjunction with the useReducer hook, you will be able to create robust React UI's, as well as iterate on top of them with much more confidence.

Summarizing everything we discussed above, these are the steps you should take to create a properly typed useReducer hook:

1- Type each action individually and create a super type, which is the union of all of them;
2 - Type each state individually and create a super type, which is the union of all of them;
3 - Add the necessary generic types to the useReducer and reducer function.

And that's it, you just improved your Developer Experience by a lot, and not only that, but by doing all these typing, you ended up creating a thin testing layer that will probably spare you from many coming bugs.

Make sure to follow me on twitter if you want read about TypeScript best practices or just web development in general!

Mastering useReducer (1/2)

Pedro Figueiredo — Sun, 13 Feb 2022 23:34:33 +0000

This blog post takes for granted that you have some knowledge regarding React and React's Hooks.

Managing state in React

As you probably know, React has 2 ways to manage state:

Both are widely used across any given React application, and although they ultimately serve the same purpose (managing state), they should be used in different situations.

When to use `useReducer` vs `useState`

useReducer is usually preferable to useState when you have complex state logic that involves multiple sub-values or when the next state depends on the previous one. - React's docs

As stated in the paragraph above, the useReducer hook should be opted in when the logic behind your state is a bit more complex or depends on the previous state.

✅ Good use cases for useReducer:

Changing 1 piece of state also changes others (co-related state values);
The state is complex and has a lot of moving parts;
When you want/need more predictable state transitions;

The `useReducer` hook

Now that we have some context on where to use this hook, it's time to take a closer look at it's API.

useReducer it's a built in function brought by React that has 2 different signatures:

useReducer(reducer, initialArg);
useReducer(reducer, initialArg, init);

`useReducer` arguments

reducer

The reducer as it's own name indicates, it's a function that takes some information and reduces it into something, and this is the place where the "magic" happens.

It takes two arguments, the current state and the action which is dispatched by the UI. By taking a given action type, a reducer will return the next piece of state, usually by deriving the previous state.

function counterReducer(state, action) {
  switch (action.type) {
    case 'increment':
      return {count: state.count + 1};
    case 'decrement':
      return {count: state.count - 1};
  }
}

initialState

This argument is pretty self explanatory, it's just the state that the useReducer hook will start with.

init

init is a function that allows you do some logic around the initial state, as it will take the value you passed as initialState and return a "new" initialState based on that.

function init(initialCount) {
  return {count: initialCount};
}

`useReducer` returned values

Very similar to useState, this hook returns an array with two values:

The first, to show the current state;
The second, a way to change the state, and create a re-render in the application.

 const [state, dispatch] = useReducer(counterReducer, initialState);

state

This value doesn't need much explanation, it is simply the current state returned by the useReducer hook.

dispatch

This is a function where you can pass the the possible actions that you define for your reducer to handle. Taking the previous counterReducer by example, these could look like this:

function Counter() {
  const [state, dispatch] = useReducer(reducer, initialState);
  return (
    <>
      <button onClick={() => dispatch({type: 'decrement'})}>-</button>
      <button onClick={() => dispatch({type: 'increment'})}>+</button>
    </>
  );
}

Managing the fetching logic with the `useReducer` hook

Now that we have a better understanding of what the useReducer hook can do for us, it's time to get our hands dirty and make usage of this React hook to handle any given fetching related state.

Fetching state

In order to use useReducer, you must first think what will be the state that you want to manage, these are usually all the things that you might have in a bunch of useState hooks, like data, errorMessage, fetchState, etc...

In this scenario, as we want to create a hook that will allow us to manage fetching logic. And as far as fetch logic goes, all the pieces you need are:

state: to know if the application is iddle, loading, if the fetch was a success or a failure
error: a error message in case something went wrong
data : the response data

And so, now that we have our state structure defined, we can setup our initialState.

// "iddle" state because we haven't fetch anything yet!
  const initialState = {
    status: "idle",
    data: null,
    error: null,
  };

Fetching reducer

Actions

The second step, is to create the logic that will lead to different app states. That logic lives under the reducer function and for us to mount that logic, we should start by thinking on the "actions" that we need to perform.

For the fetching logic, we will need the following actions:

FETCH: action to be called when the request starts;
RESOLVE: action to be called if the response is successful;
REJECT: action to be called if the requests throws an error or the response is "invalid";

Bear in mind that you can call these actions whatever you want, as long as they reflect what's being done and it makes sense for you.

State transitions

Each of these actions (FETCH, RESOLVE and REJECT) will lead to a state transition, thus, producing a new output (a new state).

So now, it's just a matter of figuring out which will be the state that each of these actions will output.

FETCH

RESOLVE

REJECT

Implementing `useReducer`

With all the pseudo-code and decisions we have made above, we are now able to take advantage of useReducer to manage the fetching logic:

  const initialState = {
    status: "idle",
    data: null,
    error: null
  };

  function fetchReducer(currentState, action) {
    switch (action.type) {
      case "FETCH":
        return {
          ...currentState,
          status: "loading"
        };
      case "RESOLVE":
        return {
          status: "success",
          data: action.data,
          error: null
        };
      case "REJECT":
        return {
          data: null,
          status: "failure",
          error: action.error
        };
      default:
        return currentState;
    }
  }

  const [state, dispatch] = React.useReducer(fetchReducer, initialState);
}

Fetching data

The implementation code is done, let's now check how would the code look look if we were fetching some data through our useReducer.

  function fetchIt() {
    // Start fetching!
    dispatch({ type: "FETCH" });
    fetch("https://www.reddit.com/r/padel.json")
      .then((response) =>
        response.json().then((result) => {
          // We got our data!
            dispatch({ type: "RESOLVE", data: result });
        })
      )
      .catch((error) => {
       // We got an error!
        dispatch({ type: "REJECT", data: error });
      });
  }

return (
    <>
      {state.status === "loading" ? <p>loading...</p> : undefined}
      {state.status === "success" ? <p>{JSON.stringify(state.data)}</p> : undefined}
      {state.status === "failure" ? <p>{JSON.stringify(state.error)}</p> : undefined}
      <button disabled={state.status === "loading"} onClick={fetchIt}>
        Fetch Data
      </button>
    </>
  );

Creating `useFetchReducer` custom hook

Now, you will probably want to use this very same code to control your application's state in every place where you are performing an HTTP request.

Luckily for us, React brings a huge composition power packed in, making our life's quite simple when creating custom hooks through other existing React hooks (useReducer in this case).

Extracting `useReducer` hook

The 1st step, is to create a new file named use-fetch-reducer.js or whatever you wanna call it, as long and it starts with use (to be identified as an hook).

The 2nd step, is to take (copy) all the code that we implemented before, and paste it inside an exported function with the name useFetchReducer. It should look something like this:

import React from "react";

export function useFetchReducer() {
  const initialState = {
    status: "idle",
    data: null,
    error: null
  };

  function fetchReducer(currentState, action) {
    switch (action.type) {
      case "FETCH":
        return {
          ...currentState,
          status: "loading"
        };
      case "RESOLVE":
        return {
          status: "success",
          data: action.data,
          error: null
        };
      case "REJECT":
        return {
          data: null,
          status: "failure",
          error: action.error
        };
      default:
        return currentState;
    }
  }

  const [state, dispatch] = React.useReducer(fetchReducer, initialState);
}

The 3rd step is to take out our useReducer result and return it instead, so that we can use state and dispatch in every other component:

//...
return React.useReducer(fetchReducer, initialState);

To wrap things up, we should make this hook as "generic" as possible, so that it can satisfy the need of every component where it's being called from. In order to get there, the 4th step passes by providing a way for consumers to set the initialData themselves, because it might not always start as null:

function useFetchReducer(initialData = null) {
  const initialState = {
    status: "idle",
    data: initialData,
    error: null
  };

//...

Using `useFetchReducer`

Import the newly created hook into your component;
Execute it as const [state, dispatch] = useFetchReducer();
Use it's state and dispatch as you would for the useReducer hook.

Running Code

Conclusion

If your app state is becoming somewhat complex and the number of useState is mounting up, it might be time to do a small switch and take advantage of useReducer instead.

If you have decided to use useReducer, follow these steps:

Think of the State you want to manage;
Think of the Actions that that will trigger state transitions;
Think for the State Transitions that will happen when calling the defined set of states.

With these thought out, it's time to write your own reducer and call the useReducer hook.

If the logic you just created can be reused across your application, create a custom hook and enjoy 😉

The 2nd part of this series will bring some type safety to the table, make sure to follow me on twitter if you don't want to miss it!

P.S. the useFetchReducer code was highly inspired into David K. Piano's code, present in this great blog post.
_

TypeScript Utility: keyof nested object

Pedro Figueiredo — Wed, 15 Dec 2021 23:37:56 +0000

In this blog post, we will learn how to build a TypeScript util type, that exposes all the key paths of an object, including the nested ones.

Why is that useful?

Have you ever built TypeScript function that receives a specific property of an object, by specifying the object and the path to that object's property? Something like this:



const person = {
  name: "John",
  age: 30,
  dog:{
    name: "Rex",
  }
}

function get<ObjectType>(object: ObjectType, path: string){
  const keys = path.split('.');
  let result = object;
  for (const key of keys) {
    result = result[key];
  }
  return result;
}

get(person, "dog.name") // Rex

Well, obviously this works very well, but you aren't taking full advantage of TypeScript! You can easily do a typo on the second argument (path) and lose some precious type with debugging this.

How can TypeScript help us then?

Unfortunately for us, there isn't yet a native utility type that can provide us all the key paths inside a nested object. But if your object only has 1 level of deepness, TypeScript's keyof operator will serve just fine!



const person = {
  name: "John",
  age: 30,
  job: "Programmer"
}

function get<ObjectType>(object: ObjectType, 
  path: keyof ObjectType & string){
 ...
}

This way, you will have a real type safe function, that will only allow you to add "name", "age" or "job" as the second argument.

If you didn't understand some of technicalities I showed above, stay with me, as I will explain in more detail bellow.

Objects with more than 1 level deepness

Now, for the objects with more than 1 level of deepness, keyof isn't nearly enough as you may have realized by now.

Before entering in TypeScript's implementation details, let's try to think of an algorithm that would allow us to get all the keys of an object with N levels of deepness.

Go through the object's keys
If the key's value is not an object , then it's a valid key
Else, if the key is an object, concat this key and go back to step 1

With this algorithm, and these "simple" programming principles, a loop statement, a conditional and recursiveness, this doesn't seem so hard after all!

Now, let's take that algorithm and build a JS function that could extract all the keys of all the nodes in any given object.



const objectKeys = [];
const person = {
    name: 'pfigueiredo',
    age: 30,
    dog: {
        owner: {
            name: 'pfigueiredo'
        }
    }
};

function getObjectKeys(obj, previousPath = '') {
    // Step 1- Go through all the keys of the object
    Object.keys(obj).forEach((key) => {
        // Get the current path and concat the previous path if necessary
        const currentPath = previousPath ? `${previousPath}.${key}` : key;
        // Step 2- If the value is a string, then add it to the keys array
        if (typeof obj[key] !== 'object') {
            objectKeys.push(currentPath);
        } else {
            objectKeys.push(currentPath);
            // Step 3- If the value is an object, then recursively call the function
            getObjectKeys(obj[key], currentPath);
        }
    });
}

getObjectKeys(person); // [ 'name', 'age', 'dog', 'dog.owner', 'dog.owner.name' ]

So, we know how to do this programmatically, the goal now, is to try and apply the same kind of concepts with TypeScript existing operators and utility types to build a generic type that will give us all the keys of an object as literal types.

Creating the TypeScript utility type

The utility type we will create bellow, is only possible since TypeScript 4.0 version was released, as it introduced literal types.

In this section, we will go step by step, on how to create a TypeScript's utility type that is capable of extract all keys inside any given object.

Type definition

The first step to create this utility, is obviously declaring a new TypeScript type and give it a name:

1- Declaring a new type



type NestedKeyOf = {};

The next step, is to make this type be "generic", meaning, it should accept any given object that we pass into it.
TypeScript already has this generic feature embedded, and it allows us to create a flexible util that can accept any given object.

2- Accept a generic type parameter



type NestedKeyOf<ObjectType> = {};

// using
type ObjectKeys = NestedKeyOf<Person>;

Adding a generic type parameter by itself doesn't restraint the type you can pass into the utility. For that, we need to add the extends keyword, in order to only accept object types - any type that follows the "key-value" pair data type.

3- Constraint the generic parameter



type NestedKeyOf<ObjectType extends object> = {};

Great, we have a defined the type's signature, now we need to do the "real work", that is, making the implementation.

Type implementation

Going back to our algorithm, the first step to create this utility is "Go through the object's keys". TypeScript makes this easy for us with something called Mapped Types, which is a way to go through an object's keys and set the value's type based on each one of the keys.

1- Going through the object's keys



// Create an object type from `ObjectType`, where the keys
// represent the keys of the `ObjectType` and the values 
// represent the values of the `ObjectType`
type NestedKeyOf<ObjectType extends object> = 
{[Key in keyof ObjectType]: ObjectType[Key]};

Now that we were able to go through all the object's keys and use them to access each one of the object's values, we can move on to the 2nd step of the algorithm: "If the key's value is not an object , then it's a valid key".

We are going to do that check by making usage of TypeScript's Conditional Types, which work as following:



// Take a `Type`, check if it "extends" `AnotherType` 
// and return a type based on that
type Example = Dog extends Animal ? number : string;

2- Checking if it's a valid key



// If the value is NOT of type `object` then 
// set it as the generated object's value type
type NestedKeyOf<ObjectType extends object> = 
{[Key in keyof ObjectType]: ObjectType[Key] extends object 
? "" /*TODO*/ 
: Key
};

// But we want what's under the object's values, 
// so we need to access it
type NestedKeyOf<ObjectType extends object> = 
{...}[keyof ObjectType];


type Person = {
    name: 'pfigueiredo',
    age: 30,
    dog: {
        owner: {
            name: 'pfigueiredo'
        }
    }
};
NestedKeyOf<Person>; // "name" | "age" | ""

So, we now have access to all the object's first level keys, but we are obviously still missing the path to the other level's properties, such as dog.owner and dog.owner.name.

In order to achieve that, we should follow the 3rd step of our algorithm: "Else, if the key is an object, concat this key and go back to step 1."

To achieve that, we need to make usage of TypeScript's recursive types, which work as any other programming language really - having a condition that calls the same "type" that invoked the condition (recursiveness), and having a condition that leads to an actual result.

3 - Add type recursiveness



// 1 - If it's an object, call the type again
type NestedKeyOf<ObjectType extends object> = 
{[Key in keyof ObjectType]: ObjectType[Key] extends object 
? NestedKeyOf<ObjectType[Key]>
: Key
}[keyof ObjectType];

// 2 - Concat the previous key to the path
type NestedKeyOf<ObjectType extends object> = 
{[Key in keyof ObjectType]: ObjectType[Key] extends object 
? `${Key}.${NestedKeyOf<ObjectType[Key]>}`
: Key
}[keyof ObjectType];

// 3 - Add the object's key
type NestedKeyOf<ObjectType extends object> = 
{[Key in keyof ObjectType]: ObjectType[Key] extends object 
? `${Key}` | `${Key}.${NestedKeyOf<ObjectType[Key]>}`
: Key
}[keyof ObjectType];

That is basically it, this NestedKeyOf utility type should already be capable of extracting all the possible property paths of an object with any given depth, but TypeScript will probably still be yelling at you for using non-strings/numbers inside the literals, let's fix that!

In order to only select keys of a specific type, we need to leverage the Intersection Types, which is just a matter of using the & operator.

4- Extracting string/number keys only



// add `& (string | number)` to the keyof ObjectType
type NestedKeyOf<ObjectType extends object> = 
{[Key in keyof ObjectType & (string | number)]: ObjectType[Key] extends object 
? `${Key}` | `${Key}.${NestedKeyOf<ObjectType[Key]>}`
: `${Key}`
}[keyof ObjectType & (string | number)];

SortBy sample with NestedKeyOf

Now that we have finalised the implementation of our TypeScript utility type, it's time to see a simple sample where it would be super useful in any project you might be working in 👇

By using this utility in the sortBy function, we are able to safely select one of the object's properties and make sure we don't do any typo and keep in sync with the object's structure and what we are passing at all times 🤯

Summary

Create a type that accepts a generic
Constraint the generic to be an object
Create a new object with the help of Mapped Types
For each key, check if the value is an object or a primitive type
If it's an object then concat the current key and call the type in a recursiveness manner
Only look for string and number keys

As a side note, I wanna appreciate the fantastic David Sherret, which posted a stack overflow answer that looked somewhat like the utility type I described above 🙏

A Cheat Sheet for CSS units

Pedro Figueiredo — Thu, 11 Nov 2021 10:55:34 +0000

This is an opinionated take on when to use each CSS unit, feel free and encouraged to disagree and make an argument on that, if that's the case.

TL;DR

REM

font-size
spacing
border-radius

letter-spacing
media-queries

border-width
shadows

Other Units

z-index (integer)
line-height (integer)
sizes (%)

CSS units

Have you ever wondered what CSS units to use on any specific case? If so, this cheat sheet will be definitely useful for you!

There are em, rem, px and many other units out there, and we always want to apply what's described as a "best practice". That's why I came up with this cheat sheet, this is something I look up for whenever I need to come up with a new theme or new design tokens.

Design tokens are all the values needed to construct and maintain a design system — spacing, color, typography, object styles, animation, etc. - by Adobe

REM

rem is a relative CSS unit that scales with the root element's font size. Meaning, that it uses the font-size that defined under the html tag to be calculated.

Why is this unit useful?

The main purpose of rem units, is related with its scaling with the document's font-size, meaning that if a user updates the font-size on the browser settings (yes, that's a thing), and if the typography is defined with rem units, everything will scale as it is meant to!

In which scenarios should I be using rem then?

You could think of this, as "whenever I want things to scale, based on the font-size". In the end, these are the design tokens where you should be using this unit:

Font-size - So that font-size scales with the defined font-size settings by the user.
Spacing - Inside this design token, lives all the CSS properties that add any sense of spacing between elements, like margin or padding. And for these, I find it useful to have it scaling with the root's font-size, so that the same visual and hierarchy effect is shown to the user.
Border-radius - This unit makes most sense to be in rem because the "box" elements that have it defined, are usually wrapping content that is also defined in rem, making it then convenient to have this "rounded" effect scaling with font-size also.

EM

em is a relative CSS unit that scales with the parent element's font-size. Meaning that if an element has a font-size of 2em, it will be the double of it's parent.

Why is this unit useful?

em units are useful when you want to have something to scale depending on the currently defined font-size. Icons are good example of this, most times you will want your icons size to be relative to whatever is the font-size defined on the context they are placed.

In which scenarios should I be using em then?

There aren't many scenarios in which this unit is useful, it's mostly when you want properties to scale depending on the context's font-size.

Letter-Spacing - letter-spacing as the name indicates, is correlated with the letters them selves, and as such it should scale with whatever is the defined font-size for this parent's element.
Media Queries - For multiple reasons that I won't enter in detail, em is the most consistent unit when it comes to media queries and works pretty well across all browsers. You can read more about this topic in this thorough blog post.

PX

px has been the most commonly used CSS unit when it comes to web development. It is an absolute unit, and 1px represents 1/96th of 1 inche.

Why is this unit useful?

px units are useful when you want to have something to be static and not change depending on factor's like the defined font-size.

In which scenarios should I be using px then?

This unit is the clear winner when it comes "let's build this fast and not put much thinking into it". But in fact, there aren't that many useful scenarios in which you should be using this unit.

Border-width - As far as borders goes, you usually just want them to add some kinda of emphasis or to separate contexts, so you really don't need them to scale depending on anything.
Shadows - We usually use shadows to give a sense of elevation or to create some type of stacking, and that's another thing where we don't need things to scale.

Other units

For the particular use case of defining values for design tokens like z-index, line-heights or sizes, I tend to not use any of the units above, and use the following "miscellaneous" instead:

Integer number

Z-index - For this CSS property, your only shot it so use an integer number, so there isn't much to say in that regard.
Line-height - Line-height's value depends on the defined font-size to set it's value, similar to how the em unit works. But there is no need to specify any CSS unit, as specifying an integer number like line-height: 2; will lead to a line-height value, that is the double of the font-size.

% value

sizes - This design token includes width and height, and having pre-defined % values like width: 50% or height: 75%, is usually what I tend to find the most useful.

Conclusion

In today's web development using px as a CSS unit for every other property isn't really a choice if you wanna makes thing right by your users.

Users should have the option to update their browser settings and still have a pretty good experience on your website, with that in mind, make sure you are using the appropriate CSS units for each property, and deliver an awesome experience!

Jest testing without the noise

Pedro Figueiredo — Wed, 03 Nov 2021 23:22:38 +0000

This post takes by granted that you already have Jest set up and a test script defined on your package.json file.

Running 1 test file at a time

You know that feeling when you you are writing Jest tests and for you to check their correctness, you need to run all of them, and on top of that, wait a couple minutes? ⌛

Well I at least did for a while.

But luckily, there is a better way! By running the following command:

npm test -- FILE_NAME

Using the command above, we will only be running the test suites inside that file! Not only that, but you don't even need to write the full name of the file, as Jest will be running against every file whose name matches the FILE_NAME's regex expression.

How to use the command

Looking at the folder structure bellow 👇

/src
  /components   
    /button      
      Button.tsx
      Button.test.tsx
      ButtonCTA.test.tsx
    /heading
      Heading.tsx
      Heading.test.tsx
    /...
package.json
...

If would run npm run test -- button you would actually be running the tests inside both Button.test.tsx and ButtonCTA.test.tsx. That is because Jest will run all the tests whose name match the following regex /button/i, making it look not only for all the file names that include the string button, but also ignoring the casing.

So, in this scenario, to only run the tests inside Button.test.tsx you should actually be typing something more restrictive like:

npm test -- button.test

Running 1 test case or 1 test suite

Now, many times we really just want to run that one test that is being "stubborn" and doesn't want to pass, at all.

We already know how to strict Jest to only run tests inside one file, but that can still take some time, depending on how many tests we have in that file.

Option 1 - Run by test name

According to Jest Docs, it is possible to only run 1 test by name, with the following comand:

npm test -- -t '<testName> OR <testSuiteName>'

But by doing so, you will not only have some probabilities of running more than 1 test (because name collapses), as well, as it will still be kinda unoptimized, since Jest must look into all the files, to check if there is any name match, thus, passing or running the tests.

Now, if we concat both flags of looking for the file name + the one to look for the test name, we could create something nice:

npm run test -- button.test -t "should render the primary button"

The command above, will only run the tests inside button.test.tsx whose name matches "should render the primary button". This way we can run a more optimized way to run the specific test we want!

Option 2 - Using `.only()`

When marking a test case/suite with .only, Jest will only run that one (you can actually mark more than one), skipping all the others.

This way, we can combine the command we learned before to run only 1 file (npm test -- button.test) and do following on top of that:

describe('Button', () => {

// Only this test will be executed inside this file
  it.only('should render the primary button', () => {
    render(<Primary {...(Primary.args as any)} />);
    expect(screen.getByRole('button')).toHaveTextContent(/Genie/i);
  });

  it('should render the secondary button', () => {
    render(<Secondary {...(Secondary.args as any)} />);
    expect(screen.getByRole('button')).toHaveTextContent(/Genie/i);
  });
});

That way, every time we run the tests pointing into the button.test.tsx file, only the test marked with .only will be executed.

Option 3 - Watch mode

Watch mode, as the name indicates, sets up a running environment that is watching for changes inside our test files.

Fortunately, watch mode brings a wizard menu, that allows us to easily filter whatever file or test we want to be watching the changes, making it way faster to execute the test!

The first step is obviously to start the watch mode with:

npm run test -- --watch

And once the menu appears, you should start by choosing the file in which the test you want to run stands - simply press "p" and start typing out the name.

Now that only 1 file's tests are being run, it's time to select the test we are interested in! And for that, you should just press "t" in the terminal and once again, choose the test by typing his name.

And magic happens 🎩! Now every time you make changes to that specific test and save the file, only that test will be executed, how cool is that!?

Conclusion

Whenever you are trying to fix that one test, stop being lazy by just running the command you have set up on your package.json file and use one of the techniques listed above!

It will not only save you some time, but also improve the overall Developer Experience.

Forem: Pedro Figueiredo

Interact with Neon APIs using Claude Code through natural language

Key components

Setting up Neon MCP Server in Claude Code

Prerequisites

Option 1: Setting up the Remote Hosted Neon MCP Server

Option 2: Setting up the Local Neon MCP Server

Verification

Supported Actions (Tools)

Development Workflow: Adding a Column with Claude Code and Neon MCP

Bonus: Creating a project and branch

Creating a new project

Creating a New Branch

Conclusion

Resources

Fixing TypeScript Dates

Dates in TypeScript

Narrowing dates information

Dates in Data Contracts

Enforcing a date format

Defining the TDateISO type

Overriding native toISOString

Summary

Conclusion

Splitting and Caching React Chunks

Code Chunks

Code Splitting

Identifying the common code

Extracting common parts into chunks

Caching Static Assets (Chunks)

CDN Distribuition

CDN Cache Invalidation

Cache Busting

File content hashing

Summary

Sources

Conclusion

Making lodash tree-shakable

Lodash

CommonJS

Tree Shaking in CommonJS

A Tree-Shakable Alternative

Tree-shaking lodash

Bonus tip

TypeScript Return Types: Separating Fact from Fiction

TypeScript Return Types

TypeScript Inference

TypeScript Functions

Infer by default

Advantages of inferring

When to use Return Types

Conclusion

2 NEW killer features coming to TypeScript

TypeScript 4.7

New features value

Instantiation Expressions

Before 4.7:

After 4.7

extends Constraints on infer Type Variables

Before 4.7

After 4.7

Conclusion

Generics vs Function Overloading vs Union Type Arguments in TypeScript

TypeScript Functions

Union Types

When to use

Function Overloading

When to use

Generic Functions

When to use

Generics vs function overloading

Which to choose

Conclusion

The bullet proof useReducer - Typescript (2/2)

Bringing TypeScript to the table

Why does it help

Typing fetchReducer

Typing Actions

Typing States

Typing reducer function

Defining the `TDateISO` type

Overriding native `toISOString`

Tree-shaking `lodash`

`extends` Constraints on `infer` Type Variables

Typing `fetchReducer`

Typing `useFetchReducer`

When to use `useReducer` vs `useState`

The `useReducer` hook

`useReducer` arguments

`useReducer` returned values

Managing the fetching logic with the `useReducer` hook

Implementing `useReducer`

Creating `useFetchReducer` custom hook

Extracting `useReducer` hook

Using `useFetchReducer`

Option 2 - Using `.only()`