README
¶
sørvør
lightning fast, zero config build tool for modern Javascript and Typescript.
Introduction
sørvør is a lightweight replacement for heavier, more complex build tools such as webpack or parcel. It is an opinionated take on esbuild with sane default and plugins to enhance your development workflow.
Major Features
- Instant Startup:
sørvøris authored in golang, which offers the best startup time for command line applications. Often times,sørvørwill finish bundling your project by the time anode.jsbundler starts loading. - Easy Installation:
sørvøris distributed as a single binary for all major platforms. It's just one command to installsørvørusing installation method of your choice. - Optimize for Production: Build for production with built-in optimizations and Asset Pipeline.
Installation
The easiest method to install sørvør is using npm or yarn:
npm install sorvor
# or
yarn add sorvor
Alternatively, if you have go installed, use go get to install sørvør:
go get github.com/osdevisnot/sorvor
Once installed, verify your installation using version flag
sorvor --version
Quickstart
You can always refer example projects for fully integrated setup using sørvør. To get started, let's set up a simple Preact application using sørvør. First, create a minimal scaffold using degit:
npx degit osdevisnot/sorvor-minimal preact-hello
The minimal scaffold comes with a README.md file with short description of available commands. Let's start the live reloading server using the command from README.md:
sorvor --serve
This should bundle your project and start a live reloading server at http://localhost:1234.
Now, let's add a simple Preact Component which renders Hello World.
import { h, render } from "preact";
const Counter = () => <div>Hello World</div>;
render(<Counter />, document.body);
You should notice an error on terminal which should look like this:
2021/02/23 09:55:58 Warn: Unexpected "<"
This error indicates sørvør was unable to parse JSX syntax we just entered. Let's restart sørvør to be able to parse JSX Syntax:
sorvor --serve --loader:.js=jsx --jsx-factory=h
On restart, your browser should display Hello World rendered using preact.
Node.js Usage
You can use sørvør to bundle browser based applications, but it is equally suitable for node.js applications as well. Let's try to build a simple express server using sørvør as build tool.
First of, create a project directory and install express as a dependency:
mkdir hello-server
cd hello-seerver
npm init --yes
npm install express
Now, let's create a server.js file in src directory, and paste below code in it:
import express from "express";
const app = express();
const port = 3000;
app.get("/", (req, res) => {
res.send("Hello World !!");
});
app.listen(port, () => {
console.log(`App Ready on http://localhost:${port}`);
});
Now, let's start the build using
sorvor src/server.js --serve --platform=node
The platform node automatically adds all the dependencies from package.json as external. The serve when combined with node platform, builds the entry file and starts running it once the build is complete. Try visiting http://localhost:3000 to see "Hello World" rendered in the browser.
Asset Pipeline
The asset pipeline for sørvør is partially inspired by HUGO pipes. To use the asset pipeline, use below annotations in your HTML entrypoint.
Live Reload
sørvør supports live reloading connected browsers based on SSE Web API.
To use this feature, include the livereload annotation in your HTML entrypoint like this:
<html>
...
<body>
{{ livereload }}
</body>
...
</html>
Bundle with esbuild
To run an entrypoint through esbuild, use esbuild annotation in your HTML entrypoint like this:
<script type="module" src="{{ esbuild "index.js" }}"></script>
Copy static files
To copy a file from source to outdir, use copy annotation in your HTML entrypoint like this:
<link rel="shortcut icon" href='{{ copy "assets/favicon.ico" }}' type="image/x-icon" />
Plugins
sørvør enhances esbuild with few quality of life plugins. These plugins are enabled by default and require no configuration for usage.
env plugin
The env plugin imports the current environment variables at build time. You can use the environment variables like this:
import { PATH } from "env";
console.log(`PATH is ${PATH}`);
Configuration
For most part, sørvør tries to use sensible defaults, but you can configure the behaviour using command line arguments below:
| cli argument | description | default value |
|---|---|---|
--host=... |
host for sørvør | localhost |
--port=... |
port for sørvør | 1234 |
--serve |
enable development mode | false |
--secure |
use https with localhost |
false |
sørvørforwards all the other command line arguments toesbuild.
--secureautomatically creates a self-signed certificate for provided host.
to disable chrome warnings, open chrome://flags/#allow-insecure-localhost and change the setting to "Enabled".
Please refer documentation for simple esbuild options or advance options to further customize the bundling process.
sørvør configures below values for esbuild as defaults which you can override using command line arguments:
| cli argument | description | default value |
|---|---|---|
--outdir=... |
target directory for esbuild output | dist |
sørvør configures below values for esbuild which can not be changed:
| cli argument | description | default value |
|---|---|---|
--bundle |
enables bundling output files | true |
--write |
enables writing built output to disk | true |
--define |
value for process.env.NODE_ENV |
production and development with --serve |
Inspirations
This project is inspired by servør from Luke Jackson, which provides similar zero dependency development experience but lacks integration with a bundler/build tools.
License
sørvør is licensed under the MIT License.
Documentation is licensed under Creative Commons License.
Created with ❤️ by @osdevisnot and all contributors.
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
pkg
|
|
|
cert
Package cert helps creating a self signed key and certs for TLS server Note: Adopted from https://golang.org/src/crypto/tls/generate_cert.go
|
Package cert helps creating a self signed key and certs for TLS server Note: Adopted from https://golang.org/src/crypto/tls/generate_cert.go |
|
livereload
Package livereload implements HTML5 Server Side Events to live reload connected browsers Usage: first start the livereload instance liveReload := livereload.New() liveReload.Start() then, install an HTTP handler on desired path http.Handle("/livereload", liveReload) then, reload the connected browsers liveReload.Reload() The target browser must support HTML5 Server Side Events.
|
Package livereload implements HTML5 Server Side Events to live reload connected browsers Usage: first start the livereload instance liveReload := livereload.New() liveReload.Start() then, install an HTTP handler on desired path http.Handle("/livereload", liveReload) then, reload the connected browsers liveReload.Reload() The target browser must support HTML5 Server Side Events. |
|
logger
Package logger provides color coded log messages with error handling
|
Package logger provides color coded log messages with error handling |
|
sorvor
Package sorvor is an extremely fast, zero config ServeIndex for modern web applications.
|
Package sorvor is an extremely fast, zero config ServeIndex for modern web applications. |