DEV Community: Ramu Narasinga

Linkedin: https://www.linkedin.com/in/ramu-narasinga-189361128/

References:

Supabase uses Valtio for its state management

Ramu Narasinga — Fri, 09 Aug 2024 22:32:08 +0000

As I was reading the Supabase source code for “fun”, I came across a package named Valtio.

I visited Valtio repository and found this in the description:

In this article, we will look at:

Proxy object.
Valtio usage with an example.
An example use case found in Supabase source code.

Proxy object

Wait, what’s a Proxy? The Proxy object enables you to create a proxy for another object, which can intercept and redefine fundamental operations for that object. (From the MDN docs). Valtio internally uses Proxy mechanism.

The below example is picked from MDN docs:

// Example 1:
const target = {
  message1: "hello",
  message2: "everyone",
};

const handler1 = {};

const proxy1 = new Proxy(target, handler1);

console.log(proxy1.message1); // hello
console.log(proxy1.message2); // everyone

// Example 2:
const target = {
  message1: "hello",
  message2: "everyone",
};

const handler2 = {
  get(target, prop, receiver) {
    return "world";
  },
};

const proxy2 = new Proxy(target, handler2);

console.log(proxy2.message1); // world
console.log(proxy2.message2); // world

Valtio usage with an example.

The following demonstration is picked from the docs.

Install

npm i valtio

Wrap your state object

Valtio turns the object you pass it into a self-aware proxy.

import { proxy, useSnapshot } from 'valtio'
const state = proxy({ count: 0, text: 'hello' })

Mutate from anywhere

You can make changes to it in the same way you would to a normal js-object.

setInterval(() => {
  ++state.count
}, 1000)

React via useSnapshot

Create a local snapshot that catches changes. Rule of thumb: read from snapshots in render function, otherwise use the source. The component will only re-render when the parts of the state you access have changed, it is render-optimized.

// This will re-render on \`state.count\` change but not on \`state.text\` change
function Counter() {
  const snap = useSnapshot(state)
  return (
    <div>
      {snap.count}
      <button onClick={() => ++state.count}>+1</button>
    </div>
  )
}

An example use case found in Supabase source code

I searched long and hard to find a simple, easy to understand example use case in Supabase source code.

The example I picked is from /apps/studio/state/app-state.ts

app-state.ts has about 95 lines of code at the time of writing this article.

// pulled from https://github.com/supabase/supabase/blob/00385657e8da32535916969036bb4e76befc5a44/apps/studio/state/app-state.ts#L57-L60
showAiSettingsModal: false,
setShowAiSettingsModal: (value: boolean) => {
  appState.showAiSettingsModal = value
},

showAiSettingsModal is found to be used in /apps/studio/components/ui/AISettingsModal.tsx

About me:

Linkedin: https://www.linkedin.com/in/ramu-narasinga-189361128/

References:

Comparing the copyToClipboard implementations in Shadcn-ui/ui and Codehike.

Ramu Narasinga — Wed, 07 Aug 2024 21:48:41 +0000

In this article, we will compare the Copy button code between Shadcn-ui/ui and Codehike.

copyToClipboard in Shadcn-ui/ui

The code snippet below is picked from shadcn-ui source code.



export async function copyToClipboardWithMeta(value: string, event?: Event) {
  navigator.clipboard.writeText(value)
  if (event) {
    trackEvent(event)
  }
}

I think ‘withMeta’ in the function name copyToClipboardWithMeta refers to the analytics recorded in the trackEvent function.



import va from "@vercel/analytics"

export function trackEvent(input: Event): void {
  const event = eventSchema.parse(input)
  if (event) {
    va.track(event.name, event.properties)
  }
}

copyToClipboard in Codehike

The code snippet below is picked from codehike source code.



function copyToClipboard(text: string) {
  if (!navigator.clipboard) {
    fallbackCopyTextToClipboard(text)
    return
  }
  navigator.clipboard.writeText(text)
}

Codehike implements the copyToClipboard differently.

There is no analytics recorded when the copyToClipboard function is called like we saw this happening in Shadcn-ui/ui.
There is a fallback method in case the navigation.clipboard API is not available.

fallbackCopyTextToClipboard:

This below code snippet is picked from Codehike source code. This function is just under the copyToClipboard.



function fallbackCopyTextToClipboard(text: string) {

  var textArea = document.createElement("textarea")

  textArea.value = text

// Avoid scrolling to bottom

  textArea.style.top = "0"

  textArea.style.left = "0"

  textArea.style.position = "fixed"

document.body.appendChild(textArea)

  textArea.focus()

  textArea.select()

try {

    var successful = document.execCommand("copy")

    // var msg = successful ? "successful" : "unsuccessful"

    // console.log("Fallback: Copying text command was " + msg)

  } catch (err) {

    // console.error("Fallback: Oops, unable to copy", err)

  }

document.body.removeChild(textArea)

}

Conclusion:

If I were to implement a copyToClipboard functionality, I would also add a fallback in case the navigator.clipboard is not available in a given browser like in Codehike and if you also use Vercel analytics in your application, you might as well record your analytics like in shadcn-ui/ui.

About me:

Linkedin: https://www.linkedin.com/in/ramu-narasinga-189361128/

References:

Shimmer effect in Card when you load Supabase dashboard.

Ramu Narasinga — Mon, 05 Aug 2024 20:54:03 +0000

When loading a dashboard, especially one as feature-rich as Supabase’s, it’s essential to provide visual feedback to users indicating that content is being loaded. A popular and visually appealing way to achieve this is by using a shimmer effect. This effect simulates a loading state and keeps users engaged while the actual content is being fetched.

Let’s explore how Supabase implements a shimmer effect in their dashboard using the animate property and some creative CSS.

Shimmer Effect Using the Animate Property

The ShimmeringCard component in Supabase's source code showcases how to create a shimmering loading effect using a combination of React and CSS animations.

Here’s the implementation of the ShimmeringCard component:

// Pulled from 
// https://github.com/supabase/supabase/blob/master/apps/studio/components/interfaces/Home/ProjectList/ShimmeringCard.tsx#L3
import CardButton from 'components/ui/CardButton'

const ShimmeringCard = () => {
  return (
    <CardButton
      className="h-44 !px-0 pt-5 pb-0"
      title={
        <div className="w-full justify-between space-y-1.5 px-5">
          <p className="flex-shrink truncate text-sm pr-4 shimmering-loader h-5 w-20" />
          <p className="text-sm lowercase text-foreground-light h-4 w-40 shimmering-loader" />
        </div>
      }
    />
  )
}
export default ShimmeringCard

In this component, CardButton is used to create the card structure, and the shimmer effect is applied to the text elements within the card using the shimmering-loader class.

The shimmering-loader CSS Class

The shimmering-loader class is defined in the main.scss file and leverages the animate property to create the shimmer effect:

.shimmering-loader {
  animation: shimmer 2s infinite linear;
  background: linear-gradient(
    to right,
    hsl(var(--border-default)) 4%,
    hsl(var(--background-surface-200)) 25%,
    hsl(var(--border-default)) 36%
  );
  background-size: 1000px 100%;
}

How It Works

Animation Definition: The shimmer keyframes animation moves the background gradient from left to right.
Gradient Background: The background is a linear gradient that creates the shimmer effect. The colors transition smoothly to give the appearance of a light moving across the surface.
Animation Application: The shimmering-loader class applies this animation to any element, making it shimmer.

About me:

Linkedin: https://www.linkedin.com/in/ramu-narasinga-189361128/

References:

Function overload in TypeScript

Ramu Narasinga — Thu, 01 Aug 2024 21:36:44 +0000

When working with TypeScript, you may encounter situations where a function needs to handle different types of input while maintaining type safety. This is where function overloading comes into play. Let’s look at a practical example of function overloading, inspired by a code snippet from the Supabase source code.

Example: useIsFeatureEnabled

The useIsFeatureEnabled function is a great example of function overloading. It can handle both an array of features and a single feature, returning appropriate results for each case.

Here’s the overloaded function definition:

function useIsFeatureEnabled<T extends Feature\[\]>(
  features: T
): { \[key in FeatureToCamelCase<T\[number\]>\]: boolean }
function useIsFeatureEnabled(features: Feature): boolean
function useIsFeatureEnabled<T extends Feature | Feature\[\]>(features: T) {
  const { profile } = useProfile()

  if (Array.isArray(features)) {
      return Object.fromEntries(
        features.map((feature) => \[
          featureToCamelCase(feature),
          checkFeature(feature, profile?.disabled\_features),
        \])
      )
  }
  return checkFeature(features, profile?.disabled\_features)
}
export { useIsFeatureEnabled }

How It Works

Function Overloads: The first two declarations are overload signatures. They define the different ways the function can be called. The actual implementation comes last, handling both cases.
Implementation: The function implementation checks if the input features is an array. If it is, it processes each feature, converts it to camelCase, and checks if it's enabled. If features is a single feature, it directly checks its status.

Supporting Functions and Types

To understand this better, let’s look at the supporting checkFeature function and the type utility FeatureToCamelCase.

checkFeature Function

The checkFeature function determines if a given feature is enabled or not:

function checkFeature(feature: Feature, features?: Feature\[\]) {
  return !features?.includes(feature) ?? true
}

This function returns true if the feature is not in the disabled features list or if no disabled features are provided.

Conclusion

Function overloading in TypeScript allows you to define multiple ways to call a function with different types of input while ensuring type safety. The useIsFeatureEnabled function from Supabase is an excellent example of this concept in action. It demonstrates how to handle different input types seamlessly, providing both flexibility and strong typing.

About me:

Linkedin: https://www.linkedin.com/in/ramu-narasinga-189361128/

References:

Convert a string to camelCase using this function in Javascript.

Ramu Narasinga — Wed, 31 Jul 2024 21:31:43 +0000

Ever needed to convert a string to camelCase? I found an interesting code snippet while exploring the open-source Supabase repository. Here’s the method they use:

function featureToCamelCase(feature: Feature) {
  return feature
    .replace(/:/g, '\_')
    .split('\_')
    .map((word, index) => (index === 0 ? word : word\[0\].toUpperCase() + word.slice(1)))
    .join('') as FeatureToCamelCase<typeof feature>
}

This function is pretty neat. It replaces colons with underscores, splits the string into words, and then maps through each word to convert it to camelCase. The first word is kept in lowercase, and the subsequent words have their first character capitalized before being joined back together. Simple yet effective!

I came across another approach on Stack Overflow that doesn’t use regular expressions. Here’s the alternative:

function toCamelCase(str) {
  return str.split(' ').map(function(word, index) {
    // If it is the first word make sure to lowercase all the chars.
    if (index == 0) {
      return word.toLowerCase();
    }
    // If it is not the first word only upper case the first char and lowercase the rest.
    return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
  }).join('');
}

This code snippet from SO has comments explaining what this code does except it does not use any sort of regex. The code found in Supabase’s way of converting a string to camelCase is very similar to this SO answer, except for the comments and the regex used.

.replace(/:/g, '\_')

This method splits the string by spaces and then maps over each word. The first word is entirely lowercased, while the subsequent words are capitalized at the first character and lowercased for the rest. Finally, the words are joined back together to form a camelCase string.

One interesting comment from a Stack Overflow user mentioned the performance advantage of this approach:

Both methods have their merits. The regex approach in the Supabase code is concise and leverages powerful string manipulation techniques. On the other hand, the non-regex approach is praised for its clarity and performance, as it avoids the computational overhead associated with regular expressions.

Here’s how you can choose between them:

Use the regex approach if you need a compact, one-liner solution that leverages JavaScript’s powerful regex capabilities. Also be sure to add comments explaining what your regex does, so that your future self or next dev working with your code can understand.
Opt for the non-regex method if you prioritize readability and performance, especially when dealing with longer strings or running this conversion multiple times.

About me:

Linkedin: https://www.linkedin.com/in/ramu-narasinga-189361128/

References:

Comparison of file and component structures among Shadcn-ui, Plane.so and Gitroom.

Ramu Narasinga — Tue, 30 Jul 2024 21:07:52 +0000

In this article, we will look at folder structures in Shadcn-ui, Plane.so and Gitroom used to organise a Next.js project.

Shadcn-ui file and component structures:

File structure

Shadcn-ui/ui uses app router and has a Router group named (app).

In the (app) folder, you will find a folder with page.tsx and/or layout.tsx in some routes such as colors, blocks, docs.

Component structure

In blocks/page.tsx, you will find that it imports components that are generic or that can be reused in other pages.

But wait, there’s other kind of components.

If you look at examples route, each example has its own component that is specific to an example.

so there’s components available at examples/card/components and then there are also generic components that can be reused.

Plane.so file and component structures:

plane.so has similar structure to that shadcn-ui/ui where you will find components specific to features by their names as shown below.

File structure

The file structure in plane.so uses nested routes but it does have a header.tsx specific to a route defined in all the folders along with page.tsx or layout.tsx

Component structure

All the components used in the app router are placed inside core folder.

So now comes the question, how come we see the imports as “@/components” in a router as shown below:

when there is no components folder at app folder level:

Well, the components are inside core folder and tsconfig.json has the paths defined to locate the folders in core as base.

Gitroom file and component structures:

Gitroom has a straight forward structure. Routes have page.tsx and each page.tsx uses components from components folder and this components folder contains files specific to features.

File structure:

As you can see, router only has one file name page.tsx and that’s it. We see in shadcn-ui where it contains components specific to a route that are scoped to that route, similarly in plane.so, it has route specific header.tsx along with page.tsx however, one commonality in all of these projects is that there is a components folder that can be reused or specific to a feature depending on the folder name.

Component structure:

Notice how the route/file structures has the folder names that match with some of the folders names in component structure.

About me:

Linkedin: https://www.linkedin.com/in/ramu-narasinga-189361128/

References:

Cache your fetcher in useSWR with useCallback.

Ramu Narasinga — Mon, 29 Jul 2024 21:04:57 +0000

I found a way that caches the fetcher in useSWR using useCallback in the Gitroom source code.

The above image is from platform-analytics/render.analytics .tsx. Let’s try to understand this code snippet.

we’ll explore how to optimize data fetching in your React applications using the useCallback hook in combination with useSWR. We'll break down the provided code snippet, explain why caching your fetcher function is important.

Understanding the Code

Let’s dive into the code step by step:

const load = useCallback(async () => {
  setLoading(true);
  const load = (
    await fetch(\`/analytics/${integration.id}?date=${date}\`)
  ).json();
  setLoading(false);
  return load;
}, \[integration, date\]);

Here, we’re defining an asynchronous function load inside a useCallback hook. This function fetches data from a specified endpoint and handles the loading state. The useCallback hook ensures that this function is memoized and only recreated when the dependencies (integration and date) change.

Next, we use useSWR to manage the data fetching:

const { data } = useSWR(\`/analytics-${integration?.id}-${date}\`, load, {
  refreshInterval: 0,
  refreshWhenHidden: false,
  revalidateOnFocus: false,
  revalidateOnReconnect: false,
  revalidateIfStale: false,
  refreshWhenOffline: false,
  revalidateOnMount: true,
});

Here, useSWR is configured with a key (/analytics-${integration?.id}-${date}) and our memoized load function. The configuration options control the revalidation behavior of the data.

How useCallback Prevents Unnecessary Re-fetches

To understand how useCallback prevents unnecessary re-fetches, we need to delve into how React handles function references and how useSWR works.

Function References in React

In React, every time a component re-renders, all functions defined within it are recreated. This means that without useCallback, a new instance of your load function would be created on every render.

Impact on useSWR

useSWR is a data fetching library for React. It uses a key to identify the data and a fetcher function to fetch it. useSWR relies on the stability of the fetcher function reference. If the reference changes, useSWR might interpret this as a signal that the data needs to be refetched, even if the actual logic of the fetcher hasn't changed.

Here’s a detailed explanation:

Without useCallback:

const load = async () => {
  setLoading(true);
  const load = (
    await fetch(\`/analytics/${integration.id}?date=${date}\`)
  ).json();
  setLoading(false);
  return load;
};

const { data } = useSWR(\`/analytics-${integration?.id}-${date}\`, load, {
  refreshInterval: 0,
  refreshWhenHidden: false,
  revalidateOnFocus: false,
  revalidateOnReconnect: false,
  revalidateIfStale: false,
  refreshWhenOffline: false,
  revalidateOnMount: true,
});

In this case, every render creates a new load function. useSWR sees a different function reference each time, which can lead to unnecessary re-fetches even when integration and date haven't changed.

With useCallback:

const load = useCallback(async () => {
  setLoading(true);
  const load = (
    await fetch(\`/analytics/${integration.id}?date=${date}\`)
  ).json();
  setLoading(false);
  return load;
}, \[integration, date\]);

const { data } = useSWR(\`/analytics-${integration?.id}-${date}\`, load, {
  refreshInterval: 0,
  refreshWhenHidden: false,
  revalidateOnFocus: false,
  revalidateOnReconnect: false,
  revalidateIfStale: false,
  refreshWhenOffline: false,
  revalidateOnMount: true,
});

By wrapping the load function in useCallback, we ensure that it is only recreated when its dependencies (integration and date) change. This stability in the function reference tells useSWR that the fetcher function hasn't changed unless integration or date changes, thus preventing unnecessary re-fetches.

About me:

Linkedin: https://www.linkedin.com/in/ramu-narasinga-189361128/

References:

Using a custom backend server with Next.js in a monorepo.

Ramu Narasinga — Fri, 26 Jul 2024 21:03:29 +0000

I was searching for an open source repository that schedules and posts on social media. I found Gitroom.

Gitroom is a awesome, built by Nevo David. You can 📨 schedule social media and articles. Exchange or buy posts from other members 👨🏻💻. Monitor your GitHub trending, and so much more 📈.

The following are some interesting things I learnt from this repository

1. You can use your own backend with Next.js 2. A note about customFetch 3. The way the files are named.

1. You can use your own backend with Next.js

Gitroom uses the following tech stack:

NX (Monorepo)
NextJS (React)
NestJS
Prisma (Default to PostgreSQL)
Redis
Resend (emails notifications)

It has folders named as frontend, backend, cron etc.,

I wondered for quite some time now, if we could use our own backend when you are already using the Next.js, a “full stack” react framework but, I kept seeing people advising to use your custom backend when you need advanced features like cron, web sockets etc., on Reddit. Now that I found Gitroom that demonstrates the custom backend usage along with Next.js and cron, I have a good feeling that you could learn some advanced patterns studying this repository.

2. A note about customFetch

The following code snippet is picked from apps/frontend/src/app/(site)/settings/page.tsx#L21

if (searchParams.code) {
  await internalFetch('/settings/github', {
  method: 'POST',
  body: JSON.stringify({ code: searchParams.code }),
  });

  return redirect('/settings', RedirectType.replace);
}

‘internalFetch’ uses customFetch.

The below code snippet is picked from libraries/helpers/src/utils/custom.fetch.func.ts

export const customFetch = (
 params: Params,
 auth?: string,
 showorg?: string
 ) => {
 return async function newFetch(url: string, options: RequestInit = {}) {
   const newRequestObject = await params?.beforeRequest?.(url, options);
   const fetchRequest = await fetch(params.baseUrl + url, {
   credentials: 'include',
   …(newRequestObject || options),
   headers: {
   …(auth ? { auth } : {}),
   …(showorg ? { showorg } : {}),
   …(options.body instanceof FormData
   ? {}
   : { 'Content-Type': 'application/json' }),
   Accept: 'application/json',
   …options?.headers,
   },
   // @ts-ignore
   …(!options.next && options.cache !== 'force-cache'
   ? { cache: options.cache || 'no-store' }
   : {}),
 });

if (
 !params?.afterRequest ||
 (await params?.afterRequest?.(url, options, fetchRequest))
 ) {
   return fetchRequest;
 }
// @ts-ignore
   return new Promise((res) => {}) as Response;
   };
};

Why???, I don’t know the answer yet but, I can tell there is “beforeRequest” and “afterRequest” processing happening based on the above code snippet

3. The way the files are named.

I have never seen a service file named using dots like “custom.fetch.func.ts”. Sure, there’s config files named as tailwind.config.ts etc.,

Here’s what chatGPT has to say about this: “ This kind of naming does not fit into a traditional case style like snake_case, kebab-case, or camelCase.

However, if we ignore the file extension (“.ts”) and consider only “custom.fetch.func,” it can be seen as:

Dot notation: This isn’t a standard case style but is sometimes used in programming to represent a hierarchical relationship or to namespace parts of a name. “

To be honest, choose w/e naming conventions work for you. I use lowercase words separated by dashes as a file name, like custom-fetch-func.ts

About me:

Linkedin: https://www.linkedin.com/in/ramu-narasinga-189361128/

Resources:

shadcn-ui/ui codebase analysis: How does shadcn-ui CLI work? — Part 3.1

Ramu Narasinga — Fri, 19 Jul 2024 22:01:53 +0000

I wanted to find out how shadcn-ui CLI works. In this article, I discuss the code used to build the shadcn-ui/ui CLI.

In part 3.0, I discussed how npx shadcn-ui add command is registered. We will look at few more lines of code from packages/cli/src/commands/add.ts.

const cwd = path.resolve(options.cwd)

if (!existsSync(cwd)) {
  logger.error(\`The path ${cwd} does not exist. Please try again.\`)
  process.exit(1)
}

const config = await getConfig(cwd)
if (!config) {
  logger.warn(
    \`Configuration is missing. Please run ${chalk.green(
      \`init\`
    )} to create a components.json file.\`
  )
  process.exit(1)
}

const registryIndex = await getRegistryIndex()

So what’s happening in the above code snippet?

Check if the cwd exists.
getConfig function.
getRegistryIndex.

Check if the cwd exists.

This code checks the current directory exists and logs an error if it doesn’t.

existsSync is imported from “fs” at the top of add.ts file.

getConfig function

getConfig is not as simple as it looks like.

const config = await getConfig(cwd)
if (!config) {
  logger.warn(
    \`Configuration is missing. Please run ${chalk.green(
      \`init\`
    )} to create a components.json file.\`
  )
  process.exit(1)
}

getConfig is imported from a different file named get-config. Reason behind this could be that context matters when it comes where you place your function. For example, logically, a function named getConfig can never be placed in a file named get-project-info.

export async function getConfig(cwd: string) {
  const config = await getRawConfig(cwd)

  if (!config) {
    return null
  }

  return await resolveConfigPaths(cwd, config)
}

This function calls another function named getRawConfig.

I explained in great detail how getConfig works in the article Part 2.2

getRegistryIndex

export async function getRegistryIndex() {
  try {
    const \[result\] = await fetchRegistry(\["index.json"\])

    return registryIndexSchema.parse(result)
  } catch (error) {
    throw new Error(\`Failed to fetch components from registry.\`)
  }
}

A simple utility function that fetches index.json available at https://ui.shadcn.com/registry/index.json

Conclusion:

Once the options and the argument passed to add command in shadcn-ui CLI, In the action, there is a lot of code, about 218 lines in add.ts. I picked a few lines of code that followed part 3.0 explanation and discussed about

Check if the cwd exists.

This code checks the current directory exists and logs an error if it doesn’t.

existsSync is imported from “fs” at the top of add.ts file.

2. getConfig function.

I explained in great detail how getConfig works in the article Part 2.2

3. getRegistryIndex.

A simple utility function that fetches index.json available at https://ui.shadcn.com/registry/index.json

About me:

Linkedin: https://www.linkedin.com/in/ramu-narasinga-189361128/

References:

shadcn-ui/ui codebase analysis: How does shadcn-ui CLI work? — Part 3.0

Ramu Narasinga — Thu, 18 Jul 2024 21:27:08 +0000

I wanted to find out how shadcn-ui CLI works. In this article, I discuss the code used to build the shadcn-ui/ui CLI.

In part 2.0 to 2.15, I discussed how npx shadcn-ui init works under the hood.

We will look at how npx shadcn-ui add works in this part 3.x.

Since the packages/cli/src/commands/add.ts file is large, I will break this analysis down into parts and talk about code snippets and explain how stuff works.

In this article, we will look the concepts:

Add command.
Commander.js package
How add command is registered?
Argument and options
addOptionsSchema

add command



export const add = new Command()
  .name("add")
  .description("add a component to your project")
  .argument("\[components...\]", "the components to add")
  .option("-y, --yes", "skip confirmation prompt.", true)
  .option("-o, --overwrite", "overwrite existing files.", false)
  .option(
    "-c, --cwd <cwd>",
    "the working directory. defaults to the current directory.",
    process.cwd()
  )
  .option("-a, --all", "add all available components", false)
  .option("-p, --path <path>", "the path to add the component to.")
  .action(async (components, opts) => {
    try {
      const options = addOptionsSchema.parse({
        components,
        ...opts,
      })

We will begin with how add command is added. The above code snippet is picked from packages/cli/src/commands/add.ts

Commander.js package:

Command is imported from commander.js, a complete solution for node.js command-line interfaces.

How add command is registered?

The way add command is registered is that, if you open this src/commands/index.ts in a new tab, you will find this code as shown below

Commands are created separately in the folder named commands for maintainability purposes. If you were to fork this shadcn-ui/ui repo and want to add your own command, this is one way to do it.

Argument and options

When you write something like npx shadcn-ui add Button, Button here is an argument.



.argument("\[components...\]", "the components to add")

The above code snippet is picked from here.

You also have options that go with your add command as shown below:



.option("-y, --yes", "skip confirmation prompt.", true)
.option("-o, --overwrite", "overwrite existing files.", false)
.option(
  "-c, --cwd <cwd>",
  "the working directory. defaults to the current directory.",
  process.cwd()
)
.option("-a, --all", "add all available components", false)
.option("-p, --path <path>", "the path to add the component to.")

and then you have action



.action(async (components, opts) => {

addOptionsSchema



 const options = addOptionsSchema.parse({
  components,
  ...opts,
})

const cwd = path.resolve(options.cwd)

if (!existsSync(cwd)) {
  logger.error(\`The path ${cwd} does not exist. Please try again.\`)
  process.exit(1)
}

The above snippet is picked from add.ts

addOptionsSchema is declared just above the add function as shown below:



const addOptionsSchema = z.object({
  components: z.array(z.string()).optional(),
  yes: z.boolean(),
  overwrite: z.boolean(),
  cwd: z.string(),
  all: z.boolean(),
  path: z.string().optional(),
})

This schema basically ensures all the options and arguments are valid before processing them further.

Conclusion:

In Part 2.0 to 2.15, I discussed how npx shadcn-ui init works under the hood. It is time for a version bump to my articles. In 3.x articles, I will write about how npx shadcn-ui add works under the hood. Please note that semver is not applicable to my articles lol.

Command is imported from commander.js, a complete solution for node.js command-line interfaces. The way add command is registered with npx shadcn-ui CLI is that, if you open this src/commands/index.ts in a new tab, you will find this code as shown below:



program.addCommand(init).addCommand(add).addCommand(diff)

There’s an argument that accepts a single component name or an array of component names, that is why you would write something like npx shadcn-ui add Button

Buttonhere is an argument. add command also has few options such -y, -o, -c, -a, -p. Read more about these in the shadcn-ui CLI documentation.

addOptionsSchema ensures that arguments and the options passed to the add command are valid using zod

About me:

Linkedin: https://www.linkedin.com/in/ramu-narasinga-189361128/

References

shadcn-ui/ui codebase analysis: How does shadcn-ui CLI work? — Part 2.15

Ramu Narasinga — Wed, 17 Jul 2024 21:26:42 +0000

I wanted to find out how shadcn-ui CLI works. In this article, I discuss the code used to build the shadcn-ui/ui CLI.

In part 2.11, we looked at runInit function and how shadcn-ui/ui ensures directories provided in resolvedPaths in config exist.

The following operations are performed in runInit function:

Ensure all resolved paths directories exist.
Write tailwind config.
Write css file.
Write cn file.
Install dependencies.

1, 2, 3, 4 from the above are covered in part 2.12, 2.13 and 2.14, let’s find out how “Install dependencies” operation is done.

Install dependencies

The below code snippet is picked from cli/src/commands/init.ts

// Install dependencies.
const dependenciesSpinner = ora(\`Installing dependencies...\`)?.start()
const packageManager = await getPackageManager(cwd)

// TODO: add support for other icon libraries.
const deps = \[
  ...PROJECT\_DEPENDENCIES,
  config.style === "new-york" ? "@radix-ui/react-icons" : "lucide-react",
\]

await execa(
  packageManager,
  \[packageManager === "npm" ? "install" : "add", ...deps\],
  {
    cwd,
  }
)
dependenciesSpinner?.succeed()

ora is an elegant terminal spinner and is used to show the message “Installing dependencies…” when you run the npx shadcn init command.

getPackageManager

getPackageManager is imported packages/cli/src/utils/get-package-manager.ts

import { detect } from "@antfu/ni"

export async function getPackageManager(
  targetDir: string
): Promise<"yarn" | "pnpm" | "bun" | "npm"> {
  const packageManager = await detect({ programmatic: true, cwd: targetDir })

  if (packageManager === "yarn@berry") return "yarn"
  if (packageManager === "pnpm@6") return "pnpm"
  if (packageManager === "bun") return "bun"

  return packageManager ?? "npm"
}

Have you ever used npm in a pnpm project? I have and often times, it fails to install the package because you are using npm in a pnpm project.

@antfu/ni lets you use the right package manager and detect is a function that gives the packageManager used in a given project based on cwd.

I cannot find anything mentioned about detect method in the @antfu/ni Github readme. How would you know such a method exists unless you read it in some open source codebase?

execa

Execa runs commands in your script, application or library. Unlike shells, it is optimized for programmatic usage. Built on top of the child_process core module. This is built by the legend, Sindre Sorhus

shadcn-ui/ui CLI uses execa to install the neccessary dependencies as part of npx shadcn-ui init command.

Conclusion

shadcn-ui CLI uses execa, built by the legend, Sindre Sorhu. Execa is used to install the necessary dependencies in a script file. We all are familiar with executing installation commands but if you want to install some packages in a script programatically, execa can be used.

shadcn-ui CLI detects the package manager used in your project using “detect” method from @antfu/ni.

This article marks my quest to study and learn what happens under the hood when you run npx shadcn-ui init command as completed.

I am moving on to study the add command.

About me:

Linkedin: https://www.linkedin.com/in/ramu-narasinga-189361128/