Clone this template to easily get started creating a new ESM package template that uses Typescript for coding, Svelte for reactive UI, Sass to enhance CSS, and Vite as the bundler tool
New to front-end web development? Check out our Web Developer Guide for the basics on each tool.
Choose this template when you need to create a new reactive UI component.
-
Visit this package on Github, press the "Use This Template" button at the top right.
-
Fill out the details for your new project like normal
-
Open the
package.json
file and change the"name"
to be the same as what you named your repository. -
Open your VSCode terminal and run
pnpm install
to install the necessary packages to your node_modules folder (this is not uploaded to your github repository)
-
This template uses Typescript, a superset of the Javascript language.
-
Typescript allows you to add type definitions for a better debugging and intellisense experience for anyone using your library. If your unfamiliar with Typescript, you can still write normal Javascript in a .ts (Typescript) file.
-
When making builds, your typescript code will become Javascript, so don't worry about compatability.
-
Your library's entry point for logic is the
./lib/main.ts
file. Write your library logic starting from that file. -
The
./test.js
file at the project root is used to load up and test your package. This script is loaded by the main entrypoint when testing (./index.html
).
-
To test your library, open the VSCode terminal and run the
pnpm run dev
command and Ctrl+Left Click on the browser link that is generated by Vite in your terminal window. -
This will open your web browser to your
index.html
page, which automatically runs the logic withintest.js
, and by default imports yourmain.ts
module. -
Any changes you make to your code will automatically compile and run in the browser link that Vite generated for you.
-
Please note that hot module replacement does not function properly with Svelte Reactive UI + Vite and has been disabled. Your code is still testable, but the state of your variables will refresh from scratch everytime you save a file.
-
To build your library for distribution, open the VSCode terminal and run the
pnpm run build
command. -
This will generate a
dist
folder containing your HTML/CSS/JS files, type definitions, sourcemaps, and other asset files. -
Make sure your
dist
folder gets uploaded to your github repo. -
It should already be set properly, but make sure your
.gitignore
is allowing files in thedist
folder to get uploaded to your repository
-
Once you have written you library, built it, and uploaded it to github. Make a new project to test it.
-
In this new project's VSCode terminal window, run the
pnpm install URL
, just replace theURL
variable at the end with the web url to the github repository for the library package you created. -
EX:
pnpm install @github:Organization/PackageName
-
This will add the library package to your
node_modules
folder, ready to be used by your new project. -
To import your code into your new projects Javascript or Typescript, use the ESM Import command
import * as Package from "package-name"
-
Replace the
package-name
with the name you wrote in thepackage.json
file of your library -
Your comments and variable type definitions should appear in the VSCode intellisense as expected
-
Your variables and functions from your library are now accessible within the
Package
variable
-
An external dependency is a package you want to use in your library, but you don't necessarily want to bundle that package's code together with your library
-
This will prevent the other package's code from appearing in your
dist
folder afterpnpm run build
is called from the VSCode terminal. -
To add an external dependency, open the
vite.config.js
file and add the name of the package you wish to turn into an external dependency to theexternal[""]
array. -
EX:
external["@babylonjs/core"]
-
This is mostly useful for very large packages (like @babylonjs/core, Svelte, React, Vue, etc). In these cases an actual application will import those large packages themselves, so you don't need to include them with your library build.
-
Developer dependencies are packages that can be used while working in VSCode, but they won't exist when
pnpm run build
is called, so they cannot be used by any code that will be part of thedist
folder. -
This can be useful for importing packages that help test your library in your
index.html
ortest.js
file, but aren't important otherwise.
-
To remove a package dependency from your library, run the
pnpm remove package-name
command in your VSCode terminal. Wherepackage-name
is the name of the package you wish to remove. -
This works for all package imports. Including developer dependencies.
-
This command will not automatically remove the name of the package from the
vite.config.js
file if you previously added it to theexternal[""]
array. You will need to manually remove those yourself.