The question
Last week I had a chat conversation with a friend who has some basic understanding of what HTML and Javascript is but wasn't familiar with tools and usage from the "modern" JS ecosystem like npm.
He wanted to use a third party web component (found on GitHub) in a simple html file.
The docs said something like:
Installation:
npm install @some-author/some-pkg
Usage:
import 'some-component';
And then just use:
<some-component></some component>
He struggled to make sense of these instructions. His mental model was "I create an index.html file and inside I have a javascript <script> tag. So where do I put what?"
I couldn't find a link to a concise article that I could send to him that would answer his question, so I wrote the following to him (and I am posting it here in case that it might useful for someone else).
My brief answer
1.) find a web component
Let's use the github/relative-time-element web component extension as an example.
What it does: If everything is properly set up, you can in your HTML part add a html tag like this:
<relative-time datetime="2026-07-24T16:30:00-08:00"></relative-time>
and it would render as something like
2 days ago
2.) bootstrap the project
So how can we create a simple html page, in which we can add the <relative-time> tag?
First, we need npm, the defacto standard package manager in the JS ecosystem. To get it, install node (nodejs). If you're on Linux you usually can install it with your package manager. Same for MacOS with homebrew and Windows with winget. Details and manual downloads are here.
Once installed, we can open a terminal and should have the npm command available.
We also need a bundler, which packs all your JS files and libraries into a few optimized files the browser can load quickly. The canonical choice here is a tool called vite.
Let's create folder for our project
mkdir demoproject
cd demoproject
Now let's bootstrap a vite project:
npm create --yes vite@latest . -- --template vanilla --no-interactive
This creates the folder structure and a minimal demo website. As we want to create our own index.html file, we can delete the clutter that we don't need:
rm index.html
rm -R src/*
Now let's install the third party node package. This will add this package locally to our project folder structure.
npm install @github/relative-time-element
3.) create a minimal index.html and a main.js file
Let's create a Javascript file that imports the third party module:
Create a new file src/main.js with:
import '@github/relative-time-element';
Now we can create a HTML file, in which we include the javascript file.
Create a new file index.html in the project root dir:
<!doctype html>
<html>
<head><title>demo</title></head>
<body>
<h1>Demo</h1>
<relative-time datetime="2026-07-24T16:30:00-08:00"></relative-time>
<script type="module" src="src/main.js"></script>
</body>
</html>
The <script> block references our main.js file. And now that we have that, we can now just add the new tag <relative-time>.
4.) How to build and run it "in prod"?
As said, the vite bundler is a kind of build step that translates our project structure into the files that we can actually put on a web server.
To build run:
npm run build
The oputput ends up in the dist/ folder:
dist
├── assets
│ └── index-D6mYi_Rf.js
├── favicon.svg
├── icons.svg
└── index.html
To preview it in a browser, we can just run npm run preview, which will spin up a web server and show a localhost URL we can click.
It's important to note that you're previewing the build that is intended to run in production. If you look at the sources in the dev tools in the browser (shortcut F12) you will notice that source files are obfuscated and minified. Which makes it hard to debug. (We'll deal with that in a moment).
5.) How to run and debug it "in dev"?
While in development, you should instead run npm run dev. This will also start a web server, which has two benefits compared to build + preview:
- you get hot reload. (You can just edit your
index.htmlorsrc/main.jsand see changes live in the browser). - through a mechanism called sourcemaps, your browser knows how the obfuscated, minified content that it receives maps back to your original source files in your project folder. So all the references in the browser dev tools are much more useful for debuging:
Top comments (0)