@ohos-ports/estrella 0.0.0-stage → 1.4.1-beta.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.gitignore +18 -0
- package/LICENSE.txt +15 -0
- package/README.md +540 -2
- package/dist/debug.js +14 -0
- package/dist/debug.js.map +1 -0
- package/dist/estrella.js +41 -0
- package/dist/estrella.js.map +1 -0
- package/dist/watch.js +6 -0
- package/dist/watch.js.map +1 -0
- package/estrella.d.ts +729 -0
- package/package.json +52 -4
package/.gitignore
ADDED
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
.DS_Store
|
|
2
|
+
*.g.*
|
|
3
|
+
*.sublime*
|
|
4
|
+
|
|
5
|
+
node_modules
|
|
6
|
+
/examples/**/out
|
|
7
|
+
/examples/**/package-lock.json
|
|
8
|
+
/examples/**/node_modules
|
|
9
|
+
/examples/**/docs/app.js*
|
|
10
|
+
/examples/**/tmp*
|
|
11
|
+
/_local
|
|
12
|
+
/dist/*.g.*
|
|
13
|
+
/dist/*.mark
|
|
14
|
+
/.test
|
|
15
|
+
/test/**/tmp-*
|
|
16
|
+
|
|
17
|
+
# typedefs copied from /estrella.d.ts to support development
|
|
18
|
+
/dist/estrella.d.ts
|
package/LICENSE.txt
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
ISC License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2020, Rasmus Andersson <rsms.me>
|
|
4
|
+
|
|
5
|
+
Permission to use, copy, modify, and/or distribute this software for any
|
|
6
|
+
purpose with or without fee is hereby granted, provided that the above
|
|
7
|
+
copyright notice and this permission notice appear in all copies.
|
|
8
|
+
|
|
9
|
+
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
|
|
10
|
+
WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
|
|
11
|
+
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
|
|
12
|
+
ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
|
13
|
+
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
|
14
|
+
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
|
|
15
|
+
OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,541 @@
|
|
|
1
|
-
|
|
1
|
+
<img src="misc/estrella-logo.png" width="320" align="center">
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Estrella is a lightweight and versatile build tool based on the fantastic
|
|
4
|
+
[esbuild](https://github.com/evanw/esbuild) TypeScript and JavaScript compiler.
|
|
5
|
+
|
|
6
|
+
- Rebuild automatically when source files change
|
|
7
|
+
- Build multiple projects at once, in parallel
|
|
8
|
+
- TypeScript diagnostics run in parallel
|
|
9
|
+
- TypeScript diagnostics are optional even for TypeScript projects
|
|
10
|
+
- Ability to remap TSXXXX TypeScript diagnostic severity levels, for example to
|
|
11
|
+
treat some issues as warnings instead of errors
|
|
12
|
+
- Scriptable — run any JavaScript you want as part of your build process
|
|
13
|
+
- Can run your program automatically when it's rebuilt
|
|
14
|
+
- [Well-tested](https://github.com/rsms/estrella/tree/master/test) code
|
|
15
|
+
- Fast!
|
|
16
|
+
|
|
17
|
+
See [estrella.d.ts](estrella.d.ts) for API documentation.
|
|
18
|
+
|
|
19
|
+
Estrella tries hard to retain the blazing startup speed of esbuild.
|
|
20
|
+
Being just a single file, with only a dependency on esbuild,
|
|
21
|
+
estrella starts very quickly.
|
|
22
|
+
`time estrella -help` completes in about 50ms with NodeJS 12.
|
|
23
|
+
Building a simple example with `time examples/minimal/build.js` completes in about 65ms.
|
|
24
|
+
|
|
25
|
+
Unlike some other "builders" Estrella does not use a config file or require you to make changes
|
|
26
|
+
to your package.json file. Instead, Estrella recognizes & embraces the fact that most projects
|
|
27
|
+
have unique build requirements. You run Estrella from a script (instead of Estrella running a
|
|
28
|
+
script or config file.) Essentially you create a "build.js",
|
|
29
|
+
or lolcat.js—name it whatever you want—script in which you invoke estrella. This turns your script
|
|
30
|
+
into a fully-featured CLI program with access to a
|
|
31
|
+
[rich API exposed by the estrella module](estrella.d.ts).
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
## Example use
|
|
35
|
+
|
|
36
|
+
1. Add Estrella to your project: `npm install -D estrella`
|
|
37
|
+
2. Create a `build.js` file in your project directory:
|
|
38
|
+
|
|
39
|
+
```js
|
|
40
|
+
#!/usr/bin/env node
|
|
41
|
+
const { build } = require("estrella")
|
|
42
|
+
build({
|
|
43
|
+
entry: "src/main.ts",
|
|
44
|
+
outfile: "out/foo.js",
|
|
45
|
+
bundle: true,
|
|
46
|
+
// pass any options to esbuild here...
|
|
47
|
+
})
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
Invoke your build script: (assumes `chmod +x build.js` has been set)
|
|
51
|
+
|
|
52
|
+
```txt
|
|
53
|
+
$ ./build.js -watch
|
|
54
|
+
Wrote out/foo.js (419 bytes, 6.84ms)
|
|
55
|
+
Watching files for changes...
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
And that's it for basic use.
|
|
59
|
+
|
|
60
|
+
[See the `examples` directory](examples) for more examples
|
|
61
|
+
which you can use as templates for new projects.
|
|
62
|
+
|
|
63
|
+
See [evanw/esbuild/lib/shared/types.ts](https://github.com/evanw/esbuild/blob/master/lib/shared/types.ts)
|
|
64
|
+
for documentation of esbuild options.
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
## TypeScript diagnostics
|
|
68
|
+
|
|
69
|
+
If there is a tsconfig.json file in the project directory,
|
|
70
|
+
or if `build({tsc:true})` is set,
|
|
71
|
+
TypeScript's `tsc` is run in parallel to esbuild, checking types and providing diagnostics:
|
|
72
|
+
|
|
73
|
+
```txt
|
|
74
|
+
$ ./build.js
|
|
75
|
+
Wrote out/foo.js (419 bytes, 7.11ms)
|
|
76
|
+
src/main.ts:2:7 - warning TS6133: 'count' is declared but its value is never read.
|
|
77
|
+
|
|
78
|
+
2 let count = 4
|
|
79
|
+
~~~~~
|
|
80
|
+
|
|
81
|
+
TS: OK 1 warning
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
What `tsc` program is run? estrella will ask nodejs to find typescript in node_modules.
|
|
85
|
+
If found, `tsc` from that package is used. Otherwise, `tsc` from the environment PATH is used.
|
|
86
|
+
This way there is no hard dependency on typescript for estrella.
|
|
87
|
+
|
|
88
|
+
estrella allows remapping the severity of TypeScript diagnostics and even filtering
|
|
89
|
+
things out completely.
|
|
90
|
+
This is particularly useful when you are converting a codebase to a stricter set of rules
|
|
91
|
+
but don't want your build to fail. For example, let's say that you enable `noImplicitAny` in
|
|
92
|
+
your tsconfig.json file. If you just run `tsc` on your project, it will fail with errors.
|
|
93
|
+
Using estrella these errors can be treated as warnings instead, still making a loud
|
|
94
|
+
appearance on screen but not causing an error exit code.
|
|
95
|
+
|
|
96
|
+
```txt
|
|
97
|
+
$ ./build.js
|
|
98
|
+
Wrote out/foo.js (14.6kb, 11.07ms)
|
|
99
|
+
src/main.ts:212:24 - error TS7006: Parameter 'ev' implicitly has an 'any' type.
|
|
100
|
+
|
|
101
|
+
212 window.onmousemove = ev => { grid.origin = [ev.clientX, ev.clientY] }
|
|
102
|
+
~~
|
|
103
|
+
TS: 1 error
|
|
104
|
+
$ echo $?
|
|
105
|
+
1
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
To make this a warning, add a rule to `build()` in your build script:
|
|
109
|
+
|
|
110
|
+
```js
|
|
111
|
+
#!/usr/bin/env node
|
|
112
|
+
const { build } = require("estrella")
|
|
113
|
+
build({
|
|
114
|
+
entry: "src/main.ts",
|
|
115
|
+
outfile: "out/foo.js",
|
|
116
|
+
bundle: true,
|
|
117
|
+
tsrules: {
|
|
118
|
+
7006: "WARNING",
|
|
119
|
+
}
|
|
120
|
+
})
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
Now if we try to build again:
|
|
124
|
+
|
|
125
|
+
```txt
|
|
126
|
+
$ ./build.js
|
|
127
|
+
Wrote out/foo.js (14.6kb, 10.42ms)
|
|
128
|
+
src/main.ts:212:24 - warning TS7006: Parameter 'ev' implicitly has an 'any' type.
|
|
129
|
+
|
|
130
|
+
212 window.onmousemove = ev => { grid.origin = [ev.clientX, ev.clientY] }
|
|
131
|
+
~~
|
|
132
|
+
TS: OK 1 warning
|
|
133
|
+
$ echo $?
|
|
134
|
+
0
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
The program exits successfully while still logging the issue.
|
|
138
|
+
|
|
139
|
+
`tsrules` is an object of type `{ [tscode:number] : "IGNORE"|"INFO"|"WARN"|"ERROR" }` which
|
|
140
|
+
maps TS diagnostic codes to:
|
|
141
|
+
|
|
142
|
+
- `"IGNORE"` completely ignore and don't even log it.
|
|
143
|
+
- `"INFO"` log it as information, unless the -quiet flag is set.
|
|
144
|
+
- `"WARN"` log it as a warning
|
|
145
|
+
- `"ERROR"` log it as an error, causing the program's exit code to be !0.
|
|
146
|
+
|
|
147
|
+
`"ERROR"` is the default for most issues.
|
|
148
|
+
Too list predefined tsrules, run: `node -p 'require("estrella").defaultTSRules'`.
|
|
149
|
+
Rules which you provide take precedence, so if there are any predefined rules you'd
|
|
150
|
+
like to change, simply set those in your `tsrules` object.
|
|
151
|
+
|
|
152
|
+
In case you need to disable TypeScript diagnostics for a project with a tsconfig.json
|
|
153
|
+
file, you can set `tslint:false` in your build config:
|
|
154
|
+
|
|
155
|
+
```js
|
|
156
|
+
build({
|
|
157
|
+
// your regular options ...
|
|
158
|
+
tslint: false,
|
|
159
|
+
})
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
|
|
163
|
+
## Examples and feature documentation
|
|
164
|
+
|
|
165
|
+
|
|
166
|
+
### Your build script becomes a CLI program
|
|
167
|
+
|
|
168
|
+
When using estrella as a library from a build script, your build script becomes a program
|
|
169
|
+
with command-line options:
|
|
170
|
+
|
|
171
|
+
```txt
|
|
172
|
+
$ ./build.js -help
|
|
173
|
+
usage: ./build.js [options]
|
|
174
|
+
options:
|
|
175
|
+
-w, -watch Watch source files for changes and rebuild.
|
|
176
|
+
-g, -debug Do not optimize and define DEBUG=true.
|
|
177
|
+
-r, -run Run the output file after a successful build.
|
|
178
|
+
-sourcemap Generate sourcemap.
|
|
179
|
+
-inline-sourcemap Generate inline sourcemap.
|
|
180
|
+
-no-color Disable use of colors.
|
|
181
|
+
-no-clear Disable clearing of the screen, regardless of TTY status.
|
|
182
|
+
-no-diag Disable TypeScript diagnostics.
|
|
183
|
+
-color Color terminal output, regardless of TTY status.
|
|
184
|
+
-diag Only run TypeScript diagnostics (no esbuild.)
|
|
185
|
+
-quiet Only log warnings and errors but nothing else.
|
|
186
|
+
-silent Don't log anything, not even errors.
|
|
187
|
+
-estrella-version Print version of estrella and exit 0.
|
|
188
|
+
-estrella-debug Enable debug logging of estrella itself.
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
You can define your own custom CLI options and parse arbitrary arguments using the `cliopts` object
|
|
192
|
+
exported by the estrella module:
|
|
193
|
+
|
|
194
|
+
```js
|
|
195
|
+
#!/usr/bin/env node
|
|
196
|
+
const { build, cliopts, file } = require("estrella")
|
|
197
|
+
const [ opts, args ] = cliopts.parse(
|
|
198
|
+
["c, cat" , "Prints a nice cat."],
|
|
199
|
+
["file" , "Show contents of <file>.", "<file>"],
|
|
200
|
+
)
|
|
201
|
+
opts.cat && console.log(stdoutStyle.pink(ASCII_cat))
|
|
202
|
+
if (opts.file) {
|
|
203
|
+
console.log(`contents of file ${opts.file}:`)
|
|
204
|
+
console.log(await file.read(opts.file, "utf8"))
|
|
205
|
+
}
|
|
206
|
+
build({ ... })
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
Ask for help to see your options documented:
|
|
210
|
+
|
|
211
|
+
```
|
|
212
|
+
./build.js -h
|
|
213
|
+
usage: ./build.js [options]
|
|
214
|
+
options:
|
|
215
|
+
[...common estrella options here...]
|
|
216
|
+
-c, -cat Prints a nice cat.
|
|
217
|
+
-file=<file> Show contents of <file>.
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
For a full example, see [examples/custom-cli-options](examples/custom-cli-options)
|
|
221
|
+
|
|
222
|
+
|
|
223
|
+
|
|
224
|
+
### Watching source files for changes
|
|
225
|
+
|
|
226
|
+
One of the key features of Estrella is its ability to watch source files for changes and rebuild
|
|
227
|
+
only the products needed. It does this in cooperation with esbuild which provides "perfect"
|
|
228
|
+
information about the source file graph for a given build product (via esbuild.metafile).
|
|
229
|
+
Estrella then uses this information to watch the relevant source files for changes and trigger a
|
|
230
|
+
rebuild. Either set `watch` in your config or pass `-watch` on the command line:
|
|
231
|
+
|
|
232
|
+
```
|
|
233
|
+
$ ./build.js -watch
|
|
234
|
+
Wrote out/main.js (341B, 8.03ms)
|
|
235
|
+
Watching files for changes...
|
|
236
|
+
|
|
237
|
+
# [make an edit to a source file]
|
|
238
|
+
1 file changed: foo.ts
|
|
239
|
+
Wrote out/main.js (341B, 10.18ms)
|
|
240
|
+
...
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
|
|
244
|
+
### Running your program
|
|
245
|
+
|
|
246
|
+
Estrella can run and manage sub processes, making it easy to run and restart your program
|
|
247
|
+
upon a successful build. Simply set `run` in your config or pass `-run` on the command line:
|
|
248
|
+
|
|
249
|
+
```
|
|
250
|
+
$ ./build.js -run
|
|
251
|
+
Hello world
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
Combining `-run` with `-watch` makes for a powerful "exploratory programming" setup where
|
|
255
|
+
changes to your source files are compiled and the results of running the program shown.
|
|
256
|
+
|
|
257
|
+
```
|
|
258
|
+
$ ./build.js -watch -run
|
|
259
|
+
Wrote out/main.js (341B, 8.21ms)
|
|
260
|
+
Running out/main.js [98609]
|
|
261
|
+
Hello world
|
|
262
|
+
out/main.js exited (0)
|
|
263
|
+
|
|
264
|
+
# [make an edit to a source file]
|
|
265
|
+
1 file changed: message.ts
|
|
266
|
+
Wrote out/main.js (341B, 8.21ms)
|
|
267
|
+
Running out/main.js [98609]
|
|
268
|
+
Hello future
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
Estrella is good at handling processes and can make a few valuable guarantees:
|
|
272
|
+
|
|
273
|
+
- A running process is always terminated before Estrella terminates.
|
|
274
|
+
The only exception to this is if the estrella process is killed with an uncapturable signal
|
|
275
|
+
like SIGKILL.
|
|
276
|
+
- A running process that is restarted is always terminates before a new instance is launched.
|
|
277
|
+
This is important if your program relies on exclusive access to resources like TCP ports or
|
|
278
|
+
UNIX sockets.
|
|
279
|
+
- Secondary subprocesses spawned by a running process are always terminated when the process
|
|
280
|
+
Estrella controls is terminated. This guarantee only applies to OSes that support signaling
|
|
281
|
+
process groups (most POSIX OSes like Linux, macOS, BSD, etc.)
|
|
282
|
+
|
|
283
|
+
"run" can be configured to run arbitrary commands by specifying `run` in your config.
|
|
284
|
+
|
|
285
|
+
Examples: (effective process invocation in comment)
|
|
286
|
+
|
|
287
|
+
```js
|
|
288
|
+
// build config // effective program invocation
|
|
289
|
+
run: true // [node, outfile] (same as `-run` on the command line)
|
|
290
|
+
run: ["deno", "file name.js"] // ["deno", "file name.js"]
|
|
291
|
+
run: "./prettier foo.js" // runs script "./prettier foo.js" in a shell
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
When `run` is set in your config, the product will be run no matter how you invoke your build
|
|
295
|
+
script. If you want to execute a more complex command that just `node outfile` while still
|
|
296
|
+
only running it when `-run` is passed on the command line, conditionally enable `run` in your
|
|
297
|
+
build script like this:
|
|
298
|
+
|
|
299
|
+
```js
|
|
300
|
+
#!/usr/bin/env node
|
|
301
|
+
const { build, cliopts } = require("estrella")
|
|
302
|
+
const p = build({
|
|
303
|
+
entry: "main.ts",
|
|
304
|
+
outfile: "out/main.js",
|
|
305
|
+
run: cliopts.run && ["/bin/zsh", "-e", "-c", "echo **/*.ts"],
|
|
306
|
+
})
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
`./build.js -run` will run your command as specified
|
|
310
|
+
while simply `./build.js` won't cause the program to run.
|
|
311
|
+
|
|
312
|
+
|
|
313
|
+
|
|
314
|
+
### Building multiple products at once
|
|
315
|
+
|
|
316
|
+
estrella can build multiple variants of your program at once.
|
|
317
|
+
Example `build.js` script:
|
|
318
|
+
|
|
319
|
+
```js
|
|
320
|
+
#!/usr/bin/env node
|
|
321
|
+
const { build } = require("estrella")
|
|
322
|
+
const common = {
|
|
323
|
+
entry: "src/main.ts",
|
|
324
|
+
bundle: true,
|
|
325
|
+
}
|
|
326
|
+
build({
|
|
327
|
+
...common,
|
|
328
|
+
outfile: "out/foo.min.js",
|
|
329
|
+
})
|
|
330
|
+
build({
|
|
331
|
+
...common,
|
|
332
|
+
outfile: "out/foo.debug.js",
|
|
333
|
+
sourcemap: true,
|
|
334
|
+
debug: true,
|
|
335
|
+
})
|
|
336
|
+
```
|
|
337
|
+
|
|
338
|
+
Then run the script to build both an optimized product and a debug product:
|
|
339
|
+
|
|
340
|
+
```txt
|
|
341
|
+
$ ./build.js
|
|
342
|
+
Wrote out/foo.min.js (445 bytes, 6.67ms)
|
|
343
|
+
Wrote out/foo.debug.{js,js.map} (2.4kb, 10.59ms)
|
|
344
|
+
TS: OK
|
|
345
|
+
```
|
|
346
|
+
|
|
347
|
+
TypeScript diagnostics are run for all unique tsconfig.json files
|
|
348
|
+
(or project directory in the absence of a tsconfig.json file), so in this case we get just
|
|
349
|
+
one report, as is expected.
|
|
350
|
+
|
|
351
|
+
In fact, since estrella is just a simple library, you can really do whatever you want
|
|
352
|
+
in your build script.
|
|
353
|
+
|
|
354
|
+
|
|
355
|
+
|
|
356
|
+
### Pre-processing and post-processing
|
|
357
|
+
|
|
358
|
+
Setting `onStart` and/or `onEnd` in a build config allows you to hook into the esbuild cycle.
|
|
359
|
+
`onStart(config, changedFiles)` is called when a build starts and `onEnd(config, result)`
|
|
360
|
+
when a build finishes.
|
|
361
|
+
This works in both `-watch` mode and regular "one shot" mode.
|
|
362
|
+
|
|
363
|
+
These callbacks can optionally be async (i.e. return a Promise) which estrella will await.
|
|
364
|
+
This gives you the ability to perform detailed pre-processing and post-processing,
|
|
365
|
+
like requesting some stuff from the internet.
|
|
366
|
+
|
|
367
|
+
Example build script using `onEnd` to show desktop notifications with
|
|
368
|
+
[node-notifier](https://github.com/mikaelbr/node-notifier) in watch mode:
|
|
369
|
+
|
|
370
|
+
```js
|
|
371
|
+
#!/usr/bin/env node
|
|
372
|
+
const { build } = require("estrella")
|
|
373
|
+
const notifier = require("node-notifier")
|
|
374
|
+
build({
|
|
375
|
+
entry: "src/main.ts",
|
|
376
|
+
outfile: "out/foo.js",
|
|
377
|
+
onEnd(config, result) {
|
|
378
|
+
config.watch && notifier.notify({
|
|
379
|
+
title: config.title,
|
|
380
|
+
message: result.errors.length > 0 ?
|
|
381
|
+
`Build failed with ${result.errors.length} errors` :
|
|
382
|
+
`Build succeeded`
|
|
383
|
+
})
|
|
384
|
+
},
|
|
385
|
+
})
|
|
386
|
+
```
|
|
387
|
+
|
|
388
|
+
|
|
389
|
+
|
|
390
|
+
### Watching arbitrary files for changes
|
|
391
|
+
|
|
392
|
+
estrella comes with functions for scanning and watching any files or directories for changes,
|
|
393
|
+
making it easy to work with other source files not handled by esbuild.
|
|
394
|
+
Like for example CSS or code generation.
|
|
395
|
+
|
|
396
|
+
Example build script:
|
|
397
|
+
|
|
398
|
+
```js
|
|
399
|
+
#!/usr/bin/env node
|
|
400
|
+
const { build, scandir, watch, cliopts } = require("estrella")
|
|
401
|
+
|
|
402
|
+
build({
|
|
403
|
+
entry: "src/main.ts",
|
|
404
|
+
outfile: "out/foo.js",
|
|
405
|
+
})
|
|
406
|
+
|
|
407
|
+
function generateCode(file) {
|
|
408
|
+
console.log(`generate ${file} -> ${file}.js`)
|
|
409
|
+
// replace with actual logic
|
|
410
|
+
}
|
|
411
|
+
|
|
412
|
+
// generate all files initially
|
|
413
|
+
const dir = "src", filter = /\..*$/i
|
|
414
|
+
scandir(dir, filter, {recursive:true}).then(files => {
|
|
415
|
+
files.map(generateCode)
|
|
416
|
+
// in watch mode, generate files as they change
|
|
417
|
+
cliopts.watch && watch(dir, {filter, recursive:true}, changes => {
|
|
418
|
+
changes.map(c => generateCode(c.name))
|
|
419
|
+
})
|
|
420
|
+
})
|
|
421
|
+
```
|
|
422
|
+
|
|
423
|
+
|
|
424
|
+
### Running a livereload web server
|
|
425
|
+
|
|
426
|
+
Say you are building a website. You may want to run a HTTP server while in watch mode
|
|
427
|
+
which automatically reloads your website as you develop it.
|
|
428
|
+
Simply run a web server like [serve-http](https://www.npmjs.com/package/serve-http)
|
|
429
|
+
in your build script:
|
|
430
|
+
|
|
431
|
+
```js
|
|
432
|
+
#!/usr/bin/env node
|
|
433
|
+
const { build, cliopts } = require("estrella")
|
|
434
|
+
build({
|
|
435
|
+
entry: "src/main.ts",
|
|
436
|
+
outfile: "docs/app.js",
|
|
437
|
+
})
|
|
438
|
+
// Run a local web server with livereload when -watch is set
|
|
439
|
+
cliopts.watch && require("serve-http").createServer({
|
|
440
|
+
port: 8181,
|
|
441
|
+
pubdir: require("path").join(__dirname, "docs"),
|
|
442
|
+
})
|
|
443
|
+
```
|
|
444
|
+
|
|
445
|
+
Now when you run your build script in watch mode a web server is run as well:
|
|
446
|
+
|
|
447
|
+
```txt
|
|
448
|
+
$ ./build.js -w
|
|
449
|
+
serving ./ at http://localhost:8181/
|
|
450
|
+
Wrote docs/app.js (914 bytes, 12.44ms)
|
|
451
|
+
TS: OK
|
|
452
|
+
```
|
|
453
|
+
|
|
454
|
+
|
|
455
|
+
### estrella as a program
|
|
456
|
+
|
|
457
|
+
estrella can also be used directly as a program:
|
|
458
|
+
|
|
459
|
+
```txt
|
|
460
|
+
$ estrella src/foo.ts -o foo.js
|
|
461
|
+
Wrote foo.js (222 bytes, 7.91ms)
|
|
462
|
+
TS: OK
|
|
463
|
+
```
|
|
464
|
+
|
|
465
|
+
```txt
|
|
466
|
+
$ estrella -h
|
|
467
|
+
usage: estrella [options] <srcfile> ...
|
|
468
|
+
options:
|
|
469
|
+
-w, -watch Watch source files for changes and rebuild.
|
|
470
|
+
-g, -debug Do not optimize and define DEBUG=true.
|
|
471
|
+
-r, -run Run the output file after a successful build.
|
|
472
|
+
-sourcemap Generate sourcemap.
|
|
473
|
+
-inline-sourcemap Generate inline sourcemap.
|
|
474
|
+
-no-color Disable use of colors.
|
|
475
|
+
-no-clear Disable clearing of the screen, regardless of TTY status.
|
|
476
|
+
-no-diag Disable TypeScript diagnostics.
|
|
477
|
+
-color Color terminal output, regardless of TTY status.
|
|
478
|
+
-diag Only run TypeScript diagnostics (no esbuild.)
|
|
479
|
+
-quiet Only log warnings and errors but nothing else.
|
|
480
|
+
-silent Don't log anything, not even errors.
|
|
481
|
+
-estrella-version Print version of estrella and exit 0.
|
|
482
|
+
-estrella-debug Enable debug logging of estrella itself.
|
|
483
|
+
-o=,-outfile=<file> Write output to <file> instead of stdout.
|
|
484
|
+
-bundle Include all dependencies.
|
|
485
|
+
-minify Simplify and compress generated code.
|
|
486
|
+
-outdir=<dir> Write output to <dir> instead of stdout.
|
|
487
|
+
-esbuild=<json> Pass arbitrary JSON to esbuild's build function.
|
|
488
|
+
|
|
489
|
+
<srcfile> is a filename, or "-" for stdin.
|
|
490
|
+
```
|
|
491
|
+
|
|
492
|
+
See `estrella -h` for more details.
|
|
493
|
+
|
|
494
|
+
|
|
495
|
+
### Developing for Estrella
|
|
496
|
+
|
|
497
|
+
Like any respectable compiler, Estrella of course builds itself.
|
|
498
|
+
|
|
499
|
+
Setup instructions:
|
|
500
|
+
|
|
501
|
+
```
|
|
502
|
+
git clone https://github.com/rsms/estrella.git
|
|
503
|
+
cd estrella
|
|
504
|
+
npm install
|
|
505
|
+
```
|
|
506
|
+
|
|
507
|
+
Build instructions:
|
|
508
|
+
|
|
509
|
+
- Build debug products: `./build.js -g` (add `-w` for incremental compilation)
|
|
510
|
+
- Build release products: `./build.js` (add `-w` for incremental compilation)
|
|
511
|
+
- Build release products and run all tests: `./test/test.sh` (or `npm test`)
|
|
512
|
+
- Build debug products and run all tests: `./test/test.sh -debug`
|
|
513
|
+
|
|
514
|
+
|
|
515
|
+
|
|
516
|
+
### Contributing to Estrella
|
|
517
|
+
|
|
518
|
+
Contributions are very welcome!
|
|
519
|
+
When contributing, please follow these guidelines:
|
|
520
|
+
|
|
521
|
+
- Use welcoming and inclusive language
|
|
522
|
+
- Be respectful of differing viewpoints and experiences
|
|
523
|
+
- Gracefully accept constructive criticism
|
|
524
|
+
- Focus on what is best for the community
|
|
525
|
+
- Show empathy towards other community members
|
|
526
|
+
|
|
527
|
+
Types of contributions and how best to make them:
|
|
528
|
+
|
|
529
|
+
- **Proposal for a new feature:**
|
|
530
|
+
[Open an issue and start a conversion.](https://github.com/rsms/estrella/issues)
|
|
531
|
+
Please do not create a PR until we've had time to discuss how to best approach the change.
|
|
532
|
+
|
|
533
|
+
- **Fix for a bug:**
|
|
534
|
+
[Please open a PR with your fix](https://github.com/rsms/estrella/pulls)
|
|
535
|
+
and if you can, include a test that fails without your change but passes with it.
|
|
536
|
+
|
|
537
|
+
- **Minor changes like spelling mistakes:**
|
|
538
|
+
[Open an issue](https://github.com/rsms/estrella/issues) and point out the concern.
|
|
539
|
+
Please do not create a PR for small things like spelling mistakes.
|
|
540
|
+
|
|
541
|
+
Thank you for being a great person & contributor!
|