UNPKG

7.64 kBMarkdownView Raw
1[![CircleCI](https://circleci.com/gh/lastmjs/zwitterion.svg?style=shield)](https://circleci.com/gh/lastmjs/zwitterion) [![npm version](https://img.shields.io/npm/v/zwitterion.svg?style=flat)](https://www.npmjs.com/package/zwitterion) [![dependency Status](https://david-dm.org/lastmjs/zwitterion/status.svg)](https://david-dm.org/lastmjs/zwitterion) [![devDependency Status](https://david-dm.org/lastmjs/zwitterion/dev-status.svg)](https://david-dm.org/lastmjs/zwitterion?type=dev)
2
3# Zwitterion
4
5Zwitterion is a server for web applications that provides automatic transpilation, live-reload, and SPA (single-page application) support out of the box. It allows you to develop web platform applications using the latest versions of JavaScript, TypeScript, JSX, TSX, or WebAssembly without a complicated build step.
6
7Just include files directly in `<script>` tags:
8
9```html
10<script src="hello-world.ts"></script>
11```
12
13or as ES module imports:
14```javascript
15import {hello} from './hello-world';
16```
17
18All features that the TypeScript compiler provides are automatically available, including ES modules, async/await, and Object spread. Zwitterion even provides support for bare specifiers:
19
20```javascript
21import {createStore} from 'redux';
22```
23
24Zwitterion lets you get back to the good old days of web development. Just write your source code and run it in the browser.
25
26## Current Features
27
28* Automatic JavaScript transpilation (JS -> JS)
29* Automatic TypeScript transpilation (TS -> JS)
30* Automatic JSX transpilation (JSX -> JS)
31* Automatic TSX transpilation (TSX -> JS)
32* Automatic WASM transpilation (WASM -> JS Module)
33* Automatic WAST transpilation (WAST -> JS Module)
34* Bare specifiers (`import * as stuff from 'library';` instead of `import * as stuff from '../node_modules/library/index.js';`)
35
36## Installation and Basic Use
37
38### Local Installation and Use
39
40Install Zwitterion in the directory that you would like to serve files from:
41
42```bash
43npm install zwitterion
44```
45
46Run Zwitterion by accessing its binary directly from the terminal:
47
48```
49node_modules/.bin/zwitterion
50```
51
52or from an npm script:
53
54```
55{
56 ...
57 "scripts": {
58 "start": "zwitterion"
59 }
60 ...
61}
62```
63
64### Global Installation and Use
65
66Install Zwitterion globally to use across projects:
67
68```bash
69npm install -g zwitterion
70```
71
72Run Zwitterion from the terminal:
73
74```bash
75zwitterion
76```
77
78or from an npm script:
79
80```
81{
82 ...
83 "scripts": {
84 "start": "zwitterion"
85 }
86 ...
87}
88```
89
90## Production Use
91
92To create a static build suitable for uploading to a CDN (content delivery network), run Zwitterion with the `--build-static` option. The static files will be created in a directory called `dist` in the directory Zwitterion is started from. You may need to add the `application/javascript` MIME type to your hosting provider for your TypeScript files.
93
94From the terminal:
95
96```bash
97zwitterion --build-static
98```
99
100From an npm script:
101
102```bash
103{
104 ...
105 "scripts": {
106 "build-static": "zwitterion --build-static"
107 }
108 ...
109}
110```
111
112## Special Considerations
113
114### Root File
115
116It's important to note that Zwitterion assumes that the root file (the file found at `/`) of your web application is always an `index.html` file. That `index.html` file must have a `<head>` element for file watching to work (this will not be required in the future).
117
118### ES Modules
119
120Zwitterion depends on native browser support for ES modules (import/export syntax). You must add the `type="module"` attribute to script tags that reference modules, for example:
121
122```
123<script type="module" src="amazing-module.ts"></script>
124```
125
126Or from a non-html file (if you leave out the file extension it will be assumed to be a TypeScript file):
127
128```
129import {amazingFunction} from './amazing-module';
130```
131
132### WASM and WAST Files
133
134Include `.wast` or `.wasm` files in your source code and imports just like any other file type. The exports of your WASM module will be available as the default export of the transpiled JS module:
135
136```wast
137;; /add.wast
138(module
139 (func $add (param i32 i32) (result i32)
140 (i32.add
141 (get_local 0)
142 (get_local 1)))
143 (export "add" (func $add)))
144```
145
146```javascript
147import AddWASM from './add.wast';
148
149console.log(AddWASM.add(2, 2));
150// 4
151```
152
153### Performance
154
155It's important to note that Zwitterion does not bundle files nor engage in tree shaking. This may impact the performance of your application. HTTP2 and ES modules may help with performance, but at this point in time signs tend to point toward worse performance. Zwitterion has plans to improve performance by automatically generating HTTP2 server push information from the static build, and looking into tree shaking, but it is unclear what affect this will have. Stay tuned for more information about performance as Zwitterion matures.
156
157With all of the above being said, the performance implications are unclear. Measure for yourself.
158
159Read the following for more information on bundling versus not bundling with HTTP2:
160
161* https://medium.com/@asyncmax/the-right-way-to-bundle-your-assets-for-faster-sites-over-http-2-437c37efe3ff
162* https://stackoverflow.com/questions/30861591/why-bundle-optimizations-are-no-longer-a-concern-in-http-2
163* http://engineering.khanacademy.org/posts/js-packaging-http2.htm
164* https://blog.newrelic.com/2016/02/09/http2-best-practices-web-performance/
165* https://mattwilcox.net/web-development/http2-for-front-end-web-developers
166* https://news.ycombinator.com/item?id=9137690
167* https://www.sitepoint.com/file-bundling-and-http2/
168* https://medium.freecodecamp.org/javascript-modules-part-2-module-bundling-5020383cf306
169* https://css-tricks.com/musings-on-http2-and-bundling/
170
171## The Future
172
173Here's a rough roadmap of the big future plans:
174
175- [ ] Investigate performance, make sure Zwitterion can beat out the complicated bundlers (tree shaking and bundling)
176- [ ] Add support for Rust, C, C++ and any other popular language that can compile to WebAssembly
177
178## Command-line Options
179
180### Port
181
182Specify the server's port:
183
184```bash
185-p [port]
186```
187
188or
189
190```bash
191--port [port]
192```
193
194### Watch Files
195
196Watch files in current directory and reload browser on changes:
197
198```bash
199-w
200```
201
202or
203
204```bash
205--watch-files
206```
207
208### Build Static
209
210Create a static build of the current working directory. The output will be in a directory called dist in the current working directory:
211
212```bash
213--build-static
214```
215
216### Exclude Dirs
217
218A space-separated list of directories to exclude from the static build:
219
220```bash
221--exclude-dirs [excludeDirs...]
222```
223
224### Target
225
226The ECMAScript version to compile to; if omitted, defaults to ES2015. Any targets supported by the TypeScript compiler are supported here (ES3, ES5, ES6/ES2015, ES2016, ES2017, ESNext):
227
228```bash
229--target [target]
230```
231
232### Disable SPA
233
234Disable the SPA redirect to index.html:
235
236```bash
237--disable-spa
238```
239
240## Under the Hood
241
242Zwitterion is simple. It is more or less a static file server, but it rewrites requested files in memory as necessary to return to the client. For example, if a TypeScript file is requested from the client, Zwitterion will retrieve the text of the file, compile it to JavaScript, compile it from CommonJS to ES Modules, and then return the compiled text to the client. The same thing is done for JavaScript files. In fact, nearly the same process will be used for any file extension that we want to support in the future. For example, in the future, if a C file is requested it will be read into memory, the text will be compiled to WebAssembly, and the WebAssembly will be returned to the client. All of this compilation is done server-side and hidden from the user. To the user, it's just a static file server.