Forem: Anupam Chakrawarti

Biome V2: Taming Your Imports for Perfect Order

Anupam Chakrawarti — Thu, 19 Jun 2025 19:23:24 +0000

Biome V2: Taming Your Imports for Perfect Order

Keeping your import statements organized is crucial for code readability and maintainability. When working on larger projects, a consistent import order can make a world of difference. Biome V2 is a powerful formatter that helps achieve this, but sometimes configuring it to your exact preferences can be a bit tricky.

Recently, a user, Cac0, faced a common challenge with Biome V2's organizeImports feature: getting npm package imports to appear at the top, followed by project-specific imports, and then other general imports. Let's dive into the problem, the debugging process, and the solution that brought order to their imports. Conaclos, a core contributor to Biome, also provided valuable insights during this discussion.

The Problem: Imports Out of Order

Cac0's goal was clear:

npm packages (like react and react-scan) at the very top.
A blank line.
Project-specific imports (e.g., components from @components, utilities from @utils).
Another blank line.
Any other imports not covered by the above.

However, despite various attempts with Biome's groups configuration, their npm package imports were consistently appearing at the bottom, not the top. They were using pnpm, React 19, and Biome v2.

Initial Troubleshooting and Misconceptions

Initial discussions revolved around Biome's predefined groups. It was clarified that :npm: isn't a valid group, but :PACKAGE: is designed to match package imports. Cac0 tried using :PACKAGE:, but the issue persisted.

One key insight came from Daryl, suggesting that the pattern @lib/* might be incorrect and should instead be @lib/** for matching multiple levels within the directory. Cac0 then revised their groups configuration to:

"groups": [
    ":NODE:",
    "./node_modules/**",
    ":PACKAGE:",
    ":BLANK_LINE:",
    ["app", "@components/**", "@lib/**", "@utils/**"],
    ":BLANK_LINE:",
    ["./**"]
]

Still, the imports weren't behaving as expected. There was a brief thought that pnpm might be the culprit, but this was ruled out as import organization is a formatter concern, not a package manager one. Emanuele also pointed out that directly matching node_modules in the groups isn't standard practice for import organization.

The Breakthrough: Aliases and `tsconfig.app.json`

The turning point came when Cac0 realized the issue wasn't solely with Biome's configuration but also with how their TypeScript aliases were defined in tsconfig.app.json.

Initially, their paths in tsconfig.app.json looked like this:

// ...
"paths": {
    "@assets/*": ["assets/*"],
    "@common/*": ["components/common/*"],
    "@lib/*": ["components/lib/*"],
    "@api/*": ["api/*"],
    "@utils/*": ["utils/*"]
}
// ...

The crucial fix was to add a forward slash (/) after the @ in the aliases:

"paths": {
    "@/assets/*": ["assets/*"],
    "@/common/*": ["components/common/*"],
    "@/lib/*": ["components/lib/*"],
    "@/api/*": ["api/*"],
    "@/utils/*": ["utils/*"]
}

This seemingly minor change had a significant impact. By using "@/lib/*" instead of "@lib/*", Cac0 theorized (and correctly so) that this new pattern for project-specific imports no longer conflicted with how Biome identifies standard npm package imports (which typically don't have @/ in their names unless they are scoped packages like @scope/package).

The Final, Working Configuration

With the updated tsconfig.app.json aliases, Cac0's Biome groups configuration finally achieved the desired import order:

// biome.json
{
  // ...
  "organizeImports": {
    "enabled": true,
    "ignore": [],
    "groups": [
      ":PACKAGE:",
      ":BLANK_LINE:",
      ["@/assets/**"],
      ":BLANK_LINE:",
      ["@/common/**", "@/lib/**", "@/api/**", "@/utils/**"],
      ":BLANK_LINE:",
      ["./**"]
    ]
  }
  // ...
}

And here's an example of how a component's imports would now be formatted correctly:

// Example Component
import { scan } from "react-scan"; // :PACKAGE:
import Test from "@/lib/test"; // Project-specific (matched by "@/lib/**")

console.log(scan);

const TextComponent: React.FC = () => {
    return (
        <div>
            Text
            <Test />
        </div>
    );
};

export default TextComponent;

Understanding Group Matching and Shadowing

Conaclos further explained an important concept: groups are matched in order, and one group matcher can "shadow" succeeding groups. This means if a broad pattern like :PACKAGE: matches all @ prefixed imports, then subsequent groups attempting to match specific @lib or @components patterns might be rendered useless.

Cac0's final solution worked because the "@/..." pattern for aliases ensures that these project-specific imports are not matched by the generic :PACKAGE: group, allowing them to be caught by their dedicated groups later in the groups array.

Note that all other imports are placed at the end by Biome's organizer, thus you can omit the `"./"` part as it represents the fallback for any unmatched imports.**

Conaclos also suggested using the predefined group :ALIAS: which matches patterns like @/**, #*/**, and ~/**, offering a more concise way to categorize alias imports:

"groups": [
    ":PACKAGE_WITH_PROTOCOL:",
    ":PACKAGE:",
    ":BLANK_LINE:",
    "@/assets/**", // Or include in :ALIAS: if applicable
    ":BLANK_LINE:",
    ":ALIAS:",
    ":BLANK_LINE:"
]

Key Takeaways

Biome's organizeImports is powerful: It offers granular control over your import order.
Understand Predefined Groups: Familiarize yourself with groups like :PACKAGE:, :NODE:, and :ALIAS:.
Order Matters: The order of your groups array is crucial, as earlier groups can shadow later ones.
Alias Configuration is Key: Ensure your TypeScript or JavaScript aliases (e.g., in tsconfig.json) are defined in a way that allows Biome to distinguish between npm packages and your project-specific modules. Using a unique prefix like ~/ or @/ for project aliases can simplify Biome's matching.
Debug Incrementally: When facing issues, start with a minimal, working configuration (perhaps from documentation) and then add your customizations step by step to identify the breaking change.
Redundant Fallbacks: Biome automatically places unmatched imports at the end, so explicit catch-all patterns like "./**" in your last group might be unnecessary.

Refer official docs: https://biomejs.dev/assist/actions/organize-imports/

Have you faced similar challenges with Biome or other formatters? Share your tips and tricks in the comments below!

Make CLI Great Again: Crafting a User-Friendly Command Line

Anupam Chakrawarti — Tue, 04 Mar 2025 17:53:35 +0000

Handling Invalid Commands
Providing Helpful Error Messages
Enabling User-Friendly Shortcuts
Utilizing Exit Codes for Status
Supporting JSON Output for Data Processing
Exposing APIs for Extensibility
Implementing Robust Validation

Handling Invalid Commands

❌ Silently fail on invalid commands or options.
✅ Provide clear suggestions or a list of similar commands instead of simply failing silently.

Scenario:

User types git staus instead of git status. Without proper handling, the CLI would just say "command not found." However, a well-designed CLI would respond with: "git: 'staus' is not a git command. Did you mean git status?" This immediately guides the user to the correct command, saving them time and frustration.

$ git poll

git: 'poll' is not a git command. See 'git --help'.

Did you mean this?

pull

$ npm ragrragr
Usage: npm <command>
where <command> is one of:
    access, add-user, adduser, apihelp, author, bin, bugs, c,
    cache, completion, config, ddp, dedupe, deprecate, dist-tag,
    dist-tags, docs, edit, explore, faq, find, find-dupes, get,
    help, help-search, home, i, info, init, install, issues, la,
    link, list, ll, ln, login, logout, ls, outdated, owner,
    pack, prefix, prune, publish, r, rb, rebuild, remove, repo,
    restart, rm, root, run-script, s, se, search, set, show,
    shrinkwrap, star, stars, start, stop, t, tag, test, tst, un,
    uninstall, unlink, unpublish, unstar, up, update, upgrade,
    v, verison, version, view, whoami
    
npm <cmd> -h     quick help on <cmd>
npm -l           display full usage info
npm faq          commonly asked questions
npm help <term>  search for help on <term>
npm help npm     involved overview

Specify configs in the ini-formatted file:
    /Users/robert/.npmrc
or on the command line via: npm <command> —key value

Config info can be viewed via: npm help config
npm@5.5.1 /Users/robert/.nvm/versions/node/v9.1.0/lib/node_modules/npm

Providing Helpful Error Messages

❌ Show technical jargon (stack trace) without proper context when the program crashes.
✅ If the order of the command is wrong, show the correct usage with examples.
✅Allow issue reporting via link. Display the stack trace and application version. Prompt the user to copy the stack trace when submitting an issue.

Scenario:

A user attempts to connect to a database using a tool, but the connection fails. A poor error message might say "Connection failed." A helpful error message would say: "Connection failed: Unable to connect to database at 192.168.1.100:5432. Please check the database server's status and your network connection." This gives the user specific information to troubleshoot the problem.

$ nmo cluster dsf
ERR! Usage:
nmo cluster get [<clustername>], [<nodename>]
nmo cluster add <nodename>, <url>, <clustername>
nmo cluster join <clustername>

$ nmo cluster join anemone

ERR! df is not defined

ERR! ReferenceError: df is not defined

ERR!     at /Users/robert/apache/nmo/lib/cluster.js:84:5

ERR!     at cli (/Users/robert/apache/nmo/lib/cluster.js:68:27)

ERR!     at /Users/robert/apache/nmo/bin/nmo-cli.js:32:6

ERR!

ERR! nmo: 1.0.1 node: v9.1.0

ERR! please open an issue including this log on https://github.com/robertkowalski/nmo/issues

Enabling User-Friendly Shortcuts

❌ Make commands explicitly clear using long names.
✅ Provide shortcuts or aliases for frequently used commands to improve efficiency and reduce typing.

Scenario:

A developer frequently uses the command npm install. By providing the shortcut npm i, they can significantly reduce the amount of typing required, especially during rapid development cycles. This small convenience adds up to a substantial time saving. Or a user might create a shortcut such as gco for the git command git checkout.

# npm 
npm install

npm i

# git

git checkout

git co

Utilizing Exit Codes for Status

❌ Use the same exit code irrespective of whether the commands succeeds or fails.
✅ Use distinct exit codes based on status. Exit code 0 indicates success, while 1 indicates failure. This allows for proper error and crash handling.

Scenario:

A script runs a backup command. If the backup fails, the command should return a non-zero exit code (e.g., 1). The script can then check the exit code and take appropriate action, such as sending an alert or retrying the backup. This is crucial for reliable automation.

$ git poll

git: 'poll' is not a git command. See 'git --help'.

Did you mean this?

  pull

$ echo $?

1

Supporting JSON Output for Data Processing

❌ Do not allow output on successful execution.
✅ Commands that return information support JSON-formatted output. This facilitates seamless integration and separate data processing with other tools and scripts, which is invaluable.

Scenario:

A system administrator uses a CLI to retrieve server information. By outputting the data in JSON format, they can easily parse and process the information using tools like jq or scripting languages like Python, enabling automated monitoring and reporting.

$ nmo cluster get --json

{ anemone:

   { node1: 'http://node1.local',

     node2: 'http://node2.local',

     node3: 'http://node3.local' } }

Exposing APIs for Extensibility

❌ Do not expose functions or API to be used by application developer to plug that in their existing solution.
✅ Provide an API layer that allows developers to integrate the CLI's core functionality into their own applications.

Scenario:

A developer wants to build a web dashboard that displays the status of a cluster managed by a CLI tool. By exposing an API, the developer can programmatically retrieve cluster information and display it in their dashboard, creating a customized user interface.

const nmo = require('nmo');

nmo.load({}).then(() => {

  nmo.commands.cluster

    .get('testcluster', 'node1@127.0.01')

    .then((res) => {

      console.log(res);

    });

})

Implementing Robust Validation

❌ Don't show error and fail silently.
✅ Validate user input early and provide clear error messages when invalid input is detected, preventing unexpected errors and crashes.

Scenario:

A user is attempting to add a URL to a configuration file. The CLI should validate that the URL is in a correct format. If the url is malformed, the application should display an error, and prevent the malformed URL from being added. This prevents the application from possibly crashing later, when it tries to use the malformed URL.

if (!/^(http:|https:)/.test(url)) {

  const err = new Error([

    'invalid protocol, must be https or http',

    'Usage: lounger isonline <url>'

  ].join('\n'));

  err.type = 'EUSAGE';

  return reject(err);

}

function errorHandler (err) {
  if (!err) {
    process.exit(1);
  }
  if (err.type === 'EUSAGE') {
    err.message && log.error(err.message);
    process.exit(1);
  }
  log.error(err);
  process.exit(1);
}

10 of my favorite open-source android apps on F-droid

Anupam Chakrawarti — Wed, 12 Feb 2025 10:27:15 +0000

We use third-party applications on our mobile devices, be it Android/iOS. Some are closed-source and others are open-source and are provided to us for use under free, paid and freemium models.

Similar to Play Store which comes pre-installed on an Android device, F-droid is an app store for Android that features only free and open-source software (FOSS). Within F-droid, you can often discover unique and privacy-focused alternatives.

Here is the website to download F-droid: https://f-droid.org/

And here are 10 of my favorite FOSS Android apps that I use on a daily basis:

Loop Habit Tracker: (Habit tracking) F-droid | GitHub
LibreTorrent: (Torrent client) F-droid | GitLab
Feeder: (RSS/Atom reader) F-droid | GitHub
AntennaPod: (Podcast player) F-droid | GitHub
Glider: (Hacker News client) F-droid | GitHub
Openreads: (Book tracker) F-droid | GitHub
Primitive FTPd: (FTP server) F-droid | GitHub
Tasks.org: (To-do list) F-droid | GitHub
LocalSend: (File sharing) F-droid | GitHub
Olauncher: (App launcher) F-droid | GitHub

Found this list helpful? If you have a GitHub account, please consider starring ⭐ the project repositories. Donations, even small ones, can help incentivize developers to continue their work.

If you come across something cool, please share it in the comments below, and I'll definitely check it out! 🍻

Use TypeScript + React effectively

Anupam Chakrawarti — Sat, 01 Feb 2025 17:43:55 +0000

Using TypeScript with React is a must in 2025. And with AI tools running rampant, it is even more important to know how to properly use TypeScript in your React project.

The AI often generates slop implementation because of its vast slopy training data and with time it will get trained on the very slop it generates.

With that note, today I share with you 5 ways to use TypeScript in your React project:

1. Discriminated Union Props with Intersection


// Bad ❌
type ButtonProps = {
    variant: "label" | "no-label";
    label?: string;
    colorCss: string;
};

// Good ✅
type ButtonProps = ({variant: "no-label"} | {variant: "label"; label: string}) & {colorCss: string};

function Button(props: ButtonProps) {
    if (props.variant === "no-label") return <button>No title</button>;
    return <button>{props.title}</button>;
};

2. Discriminated Union in useState


// Bad ❌

export function UserList() {
  const [status, setStatus] = useState({
    state: "loading",
    error: new Error(),
  });

  async function fetchUsers() {}

  useEffect(() => {
    setStatus((prev) => ({ ...prev, state: "loading" }));
    try {
      fetchUsers();
      setStatus((prev) => ({ ...prev, state: "loaded" }));
    } catch (err) {
      if (err instanceof Error) {
        setStatus({ state: "error", error: err });
      }
    }
  }, []);

  {
    status.state === "loading" ? <Loading /> : null;
  }
  {
    status.state === "error" ? <ShowError error={status?.error} /> : null;
  }
  {
    status.state === "loaded" ? <Content /> : null;
  }
}


// Good ✅

export function UserList() {
  type Status =
    | { state: "loading" }
    | { state: "loaded" }
    | { state: "error"; error: Error };

  const [status, setStatus] = useState<Status>({
    state: "loading",
  });

  async function fetchUsers() {}

  useEffect(() => {
    setStatus({ state: "loading" });
    try {
      fetchUsers();
      setStatus({ state: "loaded" });
    } catch (err) {
      if (err instanceof Error) {
        setStatus({ state: "error", error: err });
      }
    }
  }, []);

  {
    status.state === "loading" ? <Loading /> : null;
  }
  {
    status.state === "error" ? <ShowError error={status?.error} /> : null;
  }
  {
    status.state === "loaded" ? <Content /> : null;
  }
}

3. Extracting Keys and Values as Type from an Object


const RESPONSE_CODES = { 200: "Ok", 201: "Created", 202: "Accepted", 204: "No Content", 301: "Moved Permanently", 302: "Found", 304: "Not Modified", 400: "Bad Request", 401: "Unauthorized", 403: "Forbidden", 404: "Not Found", 405: "Method Not Allowed", 409: "Conflict", 500: "Internal Server Error", 501: "Not Implemented", 502: "Bad Gateway", 503: "Service Unavailable", 504: "Gateway Timeout" } as const;

type ResponseCodes = typeof RESPONSE_CODES;
type StatusCode = keyof ResponseCodes;
type StatusMessage = ResponseCodes[StatusCode];

4. Reusable components using ComponentProps


// Bad ❌
interface InputFieldProps {
    value: string;
};

// Good ✅
import { ComponentProps } from "react";

interface InputFieldProps extends ComponentProps<"input"> {
    value: string;
};

function InputField({value, ...rest}: InputFieldProps) {
    return <input value={value} {...rest} />;
};

5. Autocomplete with satisfies + ComponentProps


import { ComponentProps, PropsWithChildren } from "react";

type ButtonVariants = Record<string, ComponentProps<"button"> & {"data-testid": string}>

// Bad ❌
const buttonVariants: ButtonVariants = {
    submit: {
        type: "submit",
        className: "bg-green-300",
        "data-testid": "submit-btn"         
    },
    next: {
        type: "button",
        className: "bg-blue-300",
        "data-testid": "next-btn"       
    },
    reset: {
        type: "reset",
        className: "bg-orange-300",
        "data-testid": "reset-btn"      
    },
    delete: {
        type: "button",
        className: "bg-red-300",
        "data-testid": "delete-btn"         
    }
};

// Good ✅
const buttonVariants = {
//  ...
    delete: {
        type: "button",
        className: "bg-red-300",
        "data-testid": "delete-btn"         
    }
} satisfies ButtonVariants;

type ButtonProps = PropsWithChildren & {variant: keyof typeof buttonVariants};

function Button({children, ...rest}: ButtonProps) {
    return <button {...buttonVariants[rest.variant]}>{children}</button>
};

// Now variant will infer the types (delete, submit, next, reset) on autocomplete

<Button variant="delete">Delete record</Button>

Forem: Anupam Chakrawarti

Biome V2: Taming Your Imports for Perfect Order

Biome V2: Taming Your Imports for Perfect Order

The Problem: Imports Out of Order

Initial Troubleshooting and Misconceptions

The Breakthrough: Aliases and tsconfig.app.json

The Final, Working Configuration

Understanding Group Matching and Shadowing

Key Takeaways

Make CLI Great Again: Crafting a User-Friendly Command Line

Table Of Contents

Handling Invalid Commands

Scenario:

Providing Helpful Error Messages

Scenario:

Enabling User-Friendly Shortcuts

Scenario:

Utilizing Exit Codes for Status

Scenario:

Supporting JSON Output for Data Processing

Scenario:

Exposing APIs for Extensibility

Scenario:

Implementing Robust Validation

Scenario:

10 of my favorite open-source android apps on F-droid

Use TypeScript + React effectively

1. Discriminated Union Props with Intersection

2. Discriminated Union in useState

3. Extracting Keys and Values as Type from an Object

4. Reusable components using ComponentProps

5. Autocomplete with satisfies + ComponentProps

The Breakthrough: Aliases and `tsconfig.app.json`