1. 1
2. 2
3. 3
4. 4
5. 5
6. 6
7. 7
8. 8
9. 9
10. 10
11. 11
12. 12
13. 13
14. 14
15. 15
16. 16
17. 17
18. 18
19. 19
20. 20
21. 21
22. 22
23. 23
24. 24
25. 25
26. 26
27. 27
28. 28
29. 29
30. 30
31. 31
32. 32
33. 33
34. 34
35. 35
36. 36
37. 37
38. 38
39. 39
40. 40
41. 41
42. 42
43. 43
44. 44
45. 45
46. 46
47. 47
48. 48
49. 49
50. 50
51. 51
52. 52
53. 53
54. 54
55. 55
56. 56
57. 57
58. 58
59. 59
60. 60
61. 61
62. 62
63. 63
64. 64
65. 65
66. 66
67. 67
68. 68
69. 69
70. 70
71. 71
72. 72
73. 73
74. 74
75. 75
76. 76
77. 77
78. 78
79. 79
80. 80
81. 81
82. 82
83. 83
84. 84
85. 85
86. 86
87. 87
88. 88
89. 89
90. 90
91. 91
92. 92
93. 93
94. 94
95. 95
96. 96
97. 97
98. 98
99. 99
100. 100
101. 101
102. 102
103. 103
104. 104
105. 105
106. 106
107. 107
108. 108
109. 109
110. 110
111. 111
112. 112
113. 113
114. 114
115. 115
116. 116
117. 117
118. 118
119. 119
120. 120
121. 121
122. 122
123. 123
124. 124
125. 125
126. 126
127. 127
128. 128
129. 129
130. 130
131. 131
132. 132

# Development Guide

This document describes how to develop the ef library itself.

## Requirements

You need Bun v1, and Node.js v20 (optional).
Node.js is required for publishing the package and running benchmark on V8.

AWS CLI is also required for website deployment.

This project has `.tool-versions` file.
Use of a tool that supports reading `.tool-versions` is recommended.

## Commands

### Generate bundle files

```sh
bun scripts/bundle.ts
```

This command bundles `src/ef.js` then writes to `dist/` and `bundle.zip`.

### Check module imports

```sh
bun scripts/check-impots.ts
```

This command checks every `import`s in `src/**/*.ts`.
This command exit with non-zero code when any of import rule violations found.

### Build the website

```sh
bun scripts/website/build.ts
```

This command builds the website files then writes them to `website/dist/`.

### Build and Serve the website

```sh
bun scripts/website/serve.ts

# Rebuild when the source files are changed. Currently does not work for non ".tsx?" files due
# to a bug in Bun. Also changes to client-only file does not trigger rebuild too.
bun --hot scripts/website/serve.ts

# Specify listen port and hostname
HOST=my.domain PORT=8080 bun scripts/website/serve.ts
```

This command starts a web server and builds the website files.

### Build npm distribution files

```sh
bun run build
```

This command starts TypeScript Compiler then creates `esm/es2019/*.js` and `esm/es2019/*.d.ts`.

### Run unit tests

```sh
bun test
```

This command runs unit tests.
Add `--watch` option in order to start in watch mode.
For more options, please run the command with `--help` option.

Test files are under `tests/` directory, and have `.test.ts` extension.
Do not put test files under `src/` because that makes build configuration way more complex.

### Run example pages

```sh
bun examples
# or
bun run examples
```

This starts Vite dev server.

### Run benchmarks

```sh
# JavaScriptCore
bun bench/[path/to/suite.js]

# V8
node bench/[path/to/suite.js]
```

These command runs benchmarks.
Benchmark suites are at `bench/`, written in **plain JavaScript** because Node.js can't run TypeScript files directly.

### Run in-browser benchmark

```sh
bun bench
# then open displayed URL in your browser
```

This command starts a Vite dev server, which serves a simple HTML page that runs in-browser benchmark JS.
The script automatically starts once the page is loaded, and the result is displayed in browser console.

### Publish package to NPM

```sh
npm publish
```

### Deploy built website

```sh
bun scripts/website/deploy.ts --s3-bucket "S3 bucket name" --cf-dist-id "CloudFront distribution ID"
```

In order to authenticate, you need configure below environment variables:

- `AWS_ACCESS_KEY_ID`
- `AWS_SECRET_ACCESS_KEY`
- `AWS_DEFAULT_REGION`

Each CLI options has corresponding environment variables.

- `--s3-bucket` ... `S3_BUCKET`
- `--cf-dist-id` ... `CF_DIST_ID`