haya
Introduction
This is a dev server and a bundler based on esbuild. Very early stage, don't use it for serious projects.
This guide is heavily copied from Vite, since their usages are very similar.
Main Differences from Vite
- Haya always bundles your app, while Vite does not during development.
- Haya use esbuild for bundling, Vite uses Rollup.
- Haya only supports full page reloading, while Vite has fine-grained HMR support.
Why Haya When There's Already Vite?
Vite shines at local development, it features a no-bundle dev server which is very fast and has a very good support for HMR. Thanks to dependency prebundling with esbuild, Vite can also create a production build fast using Rollup.
The idea of Haya is not to replace Vite at development, Haya's dev server works, as long as full page reloading works for your app, but the main goal is to make the production build even faster by fully leveraging esbuild. Currently Haya can already build Vite's default starter projects, and it's trying to keep improving on that.
I plan to at least add HMR for CSS files, but HMR for JS files needs better support from esbuild itself, and it won't be there anytime soon.
Install
npm i haya -D
Quick Start
Use aho to download the starter project:
npx aho@latest egoist/haya/template my-app
cd my-app
npm i
# start dev server
npm run dev
# build for production
npm run build
# preview production build
npm run preview
Basics
Commands
-
haya [dir]
: Start dev server, treatdir
as root directory, defaults to.
-
haya build [dir]
: Build for production, output files go to[dir]/dist
-
haya preview [dir]
: Preview the production build in[dir]/dist
.
Root HTML
haya expects a index.html
file in the root directory. You can use <link>
and <script>
tags to reference and bundle external CSS and JavaScript/TypeScript.
-
<link>
should have propertyrel="stylesheet"
andhref="/some/style.css"
-
<script>
should have propertytype="module"
andsrc="/some/script.ts"
Loader
TypeScript / JavaScript
haya uses esbuild to bundle your TypeScript and JavaScript files in ES Module format, with code splitting enabled (via dynamic import).
JSX/TSX works out of the box.
CSS
The recommended way to use CSS is to use <link>
in index.html
:
<link rel="stylesheet" href="/src/style.css" />
The generated index.html
will look like:
<link rel="stylesheet" href="/0-style-[hash].css" />
However you can also directly import
CSS files in TypeScript/JavaScript files:
import "./style.css"
It will also be included in generated index.html
.
Note that the exported value of CSS files will be the its URL:
import style from "./style.css"
console.log(style)
//=> /style-[hash].css
If you want to get the URL without adding the CSS file to generated index.html
, append ?import-only
query to the module name:
import style from "./style.css?import-only"
PostCSS
Adding a postcss.config.js
or postcss.config.cjs
in your root directory to enable postcss.
Vue / Svelte
LESS SOON.
Guide
Hot Module Replacement
There is NO hot module replacement, instead it does a full reloading of the page when a rebuild occurs.
Path Alias
You can directly configure aliases via tsconfig.json
like this:
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"~/*": ["./src/*"]
}
}
}
Now ~/main
will be resolved to ./src/main
.
Env Variables
haya exposes env variables on the process.env
object. Some built-in variables are available in all cases:
-
process.env.NODE_ENV
:development
in dev orproduction
in production. We also have a special global variable__DEV__
which evaluates totrue
in dev andfalse
in production.
.env
Files
haya uses dotenv to load additional environment variables from the following files in root directory:
.env # loaded in all cases
.env.local # loaded in all cases, ignored by git
.env.[mode] # only loaded in specified mode
.env.[mode].local # only loaded in specified mode, ignored by git
Loaded env variables are also exposed to your client source code via process.env
.
To prevent accidentally leaking env variables to the client, only variables prefixed with HAYA_
are exposed to your haya-processed code. e.g. the following file:
DB_PASSWORD=foobar
HAYA_SOME_KEY=123
Only HAYA_SOME_KEY
will be exposed as process.env.HAYA_SOME_KEY
to your client source code, but DB_PASSWORD
will not.
public
directory
The If you have assets that are:
- Never referenced in source code (e.g.
robots.txt
) - Must retain the exact same file name (without hashing)
- ...or you simply don't want to have to import an asset first just to get its URL
Then you can place the asset in a special public directory under your project root. Assets in this directory will be served at root path
/
during dev, and copied to the root of the dist directory as-is.
The directory defaults to <root>/public
, but can be configured via the .publicDir
option (not yet)
Note that:
- You should always reference public assets using root absolute path - for example,
public/icon.png
should be referenced in source code as /icon.png. - Assets in
public
cannot be imported from JavaScript.
Deploying a Static Site
The output directory dist
can be served as a static website, you can preview it locally using the haya preview
command.
Roadmap
- [x] PostCSS / Tailwind support.
- [ ] Vue / Svelte support.
- [ ] SSR support, like the
ssrLoadModule
API from Vite. - [ ] Testing framework, like Vitest but for haya.
Sponsors
License
MIT © EGOIST