Skip to content

Latest commit

 

History

History
207 lines (134 loc) · 7.26 KB

README.md

File metadata and controls

207 lines (134 loc) · 7.26 KB
Raw

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ør is authored in golang, which offers the best startup time for command line applications. Often times, sørvør will finish bundling your project by the time a node.js bundler starts loading.
  • Easy Installation: sørvør is distributed as a single binary for all major platforms. It's just one command to install sørvør using 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ør forwards all the other command line arguments to esbuild.

--secure automatically 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.