[LibraUI Development Journal #5] The Significance of Integrating LibraUI Source Code via npx Command

Hello everyone, I'm Kihei, and I'm currently deep in the development of Libra UI.
Although I aim to upload a note article at least once a week, usually on the weekend, I've been so focused on development, or I've been so overcome by sleepiness on weekday nights that I've ended up falling asleep without even opening my Chromebook.

Now, this article might not be very relevant to those who don't publish components or libraries to npm. However, I would like to talk about the process that led me to the theme of 'Why go out of my way to have the source code integrated via npx?' and the struggles I faced behind the scenes.

Do you know the difference between npm install and npx?

If you are involved in frontend development, you likely use commands like npm install and npx often. (By the way, I'm a C# developer, so I only use them when doing frontend development.)

For many libraries like Material UI, it is common to integrate them into your project using 'npm install [library name]'. Honestly, I had also been vaguely wondering for a long time, 'What is the difference between npm install and npx?'
In the midst of that, it was around the beginning of this year, I think. When I was looking for React UI components, I learned about the existence of shadcn. This encounter was shocking to me.
This is because, until then, UI components were developed under provided specifications, and their internal structures could not be changed; they were in a state of what you might call black box.

However, shadcn was different.
'You can make the library's code a part of your own project'

I felt that this had the potential to revolutionize the way frontend development is done. Unlike dramatic changes like AI, it resolves the dissatisfaction of 'This isn't the UI component that my company (or I) wants to make...' It changes into a new development experience where you 'introduce a skeleton (headless) and customize the look and movement.'

The beginning of the struggle and the reality behind npm publishing

I felt that this kind of development experience would become mainstream in the future. And currently, SolidJS does not have a wealth of such headless UI components.
If that's the case, I have no choice but to make them. That's what I thought when I developed Libra UI.

In my previous article, I announced that I had finally published it to npm. However, when I checked it myself afterward, it didn't work at all.
From here on is the main topic of this article. I will talk about the specific problems I faced when I tried to import components into my developer source code using the npx command after publishing to npm, and the solutions to them.

The first trial: Struggling with mysterious error messages

When I ran the npx command in my own project, the first thing that appeared before me was an unfamiliar error message like this.

import: not found
Permission denied
Syntax error: "(" unexpected

import: not found? () is unexpected? At first, I thought it was a JavaScript syntax error, but it looked correct no matter how I looked at it. I spent hours reviewing the code and tweaking the build settings, but I couldn't figure out the cause at all.

In conclusion, this was not a code problem, but a problem with the execution environment.

The JavaScript file (.mjs) I published was being executed by the OS's default shell (sh, bash, etc.) instead of Node.js. In other words, the shell did not understand the import syntax or the function's (), and treated them as syntax errors.

Once the cause was known, the solution was clear. I solved it by adding the following string to the beginning of the .mjs file so that it would be executed by Node.js instead of the shell.

#!/usr/bin/env node

This is definitely a problem I couldn't have solved on my own without asking AI...

The second trial: The wall of type checking

Just when I thought I could import it successfully, an error occurred in the type checking of the development environment.

'Huh? This error didn't appear when I built it on the component side...'

The cause was deep-rooted, involving subtle differences between the TypeScript configuration used when developing the components and the configuration of the project using them.

Specifically, the TypeScript "strict mode" settings differed between my project and the user's project. Because the component-side environment was set to not perform strict type checking, no errors occurred, but in the project tested via npx, strict: true was enabled, triggering more rigorous checks.

To resolve this issue, I unified the component-side settings to strict: true and introduced strict type checking.

The View Beyond the Struggle

Through this series of troubles, I keenly felt the responsibility of publishing a library via npx. That is, "I must provide developers who use it with a safer and more reliable library."

I realized that behind the npx commands we use casually and the OSS (Open Source Software) that is published, there is a vast amount of trial and error like this.

The problems I struggled with have likely been experienced by OSS developers overseas as well. Even so, they make various efforts and adjustments behind the scenes so that users can use them comfortably. I felt a renewed sense of gratitude for that.

Using this experience as a stepping stone, I will continue to develop Libra UI with the goal of "delivering the best development experience to users."

The current version of Libra UI (https://github.com/OkihiraHijirikawa/solid-libra-ui) is now v0.2.2. As a result of trying to integrate the source code via npx, I had to review various things and re-examine the directory structure, so it has been updated as a minor version in that sense.

First, I have to work hard until it reaches v1.0.0!