10 |
11 |
12 | For a simplified example of `esx` in action, check out [esx-demo](https://github.com/esxjs/esx-demo).
13 |
14 | `esx` is designed to be a **high speed SSR template engine for React**.
15 |
16 | It can be used with **absolutely no code base changes**.
17 |
18 | Use it with a [preloader flag](https://nodejs.org/api/cli.html#cli_r_require_module) like so:
19 |
20 | ```sh
21 | node -r esx/optimize my-app.js
22 | ```
23 |
24 | *Note: transpiling is still experimental*.
25 |
26 | Alternatively [babel-plugin-esx-ssr](https://github.com/esxjs/babel-plugin-esx-ssr) can be used to transpile for the same performance gains. The babel plugin would be a preferred option where speed of process initialization is important (such as serverless).
27 |
28 | Optionally, `esx` is also a universal **JSX-like syntax in plain JavaScript** that allows for the elimination of transpilation in development environments.
29 |
30 | * For the server side, using `esx` syntax will yield the same high speed results as the optimizing preloader
31 | * For client side development, using `esx` syntax can enhance development workflow by removing the need for browser transpilation when developing in modern browsers
32 | * For client side production `esx` can be compiled away for production with [babel-plugin-esx-browser](https://github.com/esxjs/babel-plugin-esx-browser), resulting in zero-byte payload overhead.
33 |
34 | It uses native [Tagged Templates](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#Tagged_templates) and works in all modern browsers.
35 |
36 |
37 | 
38 |
`
77 | - Self-closing tags: ``
78 | - Attributes: `
` and `
`
79 | - Boolean attributes: ``
80 | - Components: `Todo
173 |
174 |
398 |
399 |
400 |
401 |
402 |
403 | ## Prior Art
404 |
405 | ### ESX
406 | `esx` was preceded by... `esx`. The `esx` namespace was registered four years ago
407 | by a prior author [Mattéo Delabre ](https://github.com/matteodelabre), with a similar
408 | idea. He kindly donated the namespace to this particular manifestation of the idea.
409 | For this reason, `esx` versioning begins at v2.x.x. Versions 0.x.x and 1.x.x are deprecated.
410 |
411 | ### Hyperx
412 |
413 | `esx` is directly inspired by [`hyperx`](https://npm.im/hyperx), which
414 | was the first known library to this authors knowledge to make the point
415 | that template strings are perfect for generating both virtual doms
416 | and server side rendering. What `hyperx` lacks, however, is a way
417 | to represent React components within its template syntax. It is *only*
418 | for generating HTML nodes.
419 |
420 | ### HTM
421 |
422 | It's not uncommon for similar ideas to be had and implemented concurrently
423 | without either party knowing of the other.
424 | While [`htm`](https://github.com/developit/htm) was first released early 2019,
425 | work on `esx` had already been on-going some months prior. However the
426 | mission of `esx` is slightly broader, with a primary objective being to speed up
427 | server side rendering, so it took longer to release.
428 |
429 | ## License
430 |
431 | [MIT](./LICENSE)
432 |
433 | ## Sponsors
434 |
435 | * [nearForm](https://nearform.com)
436 |
--------------------------------------------------------------------------------
/test/create.test.js:
--------------------------------------------------------------------------------
1 | 'use strict'
2 | /* eslint-env node */
3 | let test = require('aquatap')
4 | const renderer = require('react-test-renderer')
5 | const PropTypes = require('prop-types')
6 | const render = (o) => renderer.create(o).toJSON()
7 | const React = require('react')
8 | const { createElement } = React
9 | const init = process.env.TEST_CLIENT_CODE ? require('../browser') : require('..')
10 | const { MODE } = process.env
11 | if (typeof window === 'undefined') {
12 | if (!MODE) {
13 | process.env.MODE = 'development'
14 | const error = console.error.bind(console)
15 | console.error = (s, ...args) => {
16 | if (/Warning:/.test(s)) return
17 | return error(s, ...args)
18 | }
19 | delete require.cache[require.resolve(__filename)]
20 | require(__filename)
21 | test = () => {}
22 | test.only = test
23 | } else {
24 | process.env.NODE_ENV = MODE
25 | if (MODE === 'development') {
26 | process.nextTick(() => {
27 | process.env.MODE = 'production'
28 | delete require.cache[require.resolve(__filename)]
29 | require(__filename)
30 | })
31 | }
32 | }
33 | }
34 |
35 | test('components parameter must be a plain object or undefined', async ({ throws, doesNotThrow }) => {
36 | throws(() => init(null), Error('ESX: supplied components must be a plain object'))
37 | throws(() => init(() => {}), Error('ESX: supplied components must be a plain object'))
38 | throws(() => init([]), Error('ESX: supplied components must be a plain object'))
39 | throws(() => init(Symbol('test')), Error('ESX: supplied components must be a plain object'))
40 | throws(() => init(1), Error('ESX: supplied components must be a plain object'))
41 | throws(() => init('str'), Error('ESX: supplied components must be a plain object'))
42 | throws(() => init(new (class {})()))
43 | doesNotThrow(() => init())
44 | doesNotThrow(() => init(undefined))
45 | doesNotThrow(() => init({}))
46 | })
47 |
48 | test('components object must contain only uppercase property keys', async ({ throws, doesNotThrow }) => {
49 | throws(() => init({ component: () => {} }), Error(`ESX: component is not valid. All components should use PascalCase`))
50 | doesNotThrow(() => init({ Component: () => {} }))
51 | })
52 |
53 | test('components object values must be function,classes,symbols,strings or objects with a $$typeof key', async ({ throws, doesNotThrow }) => {
54 | throws(() => init({ Component: undefined }), Error(`ESX: Component is not a valid component`))
55 | throws(() => init({ Component: null }), Error(`ESX: Component is not a valid component`))
56 | throws(() => init({ Component: 1 }), Error(`ESX: Component is not a valid component`))
57 | throws(() => init({ Component: {} }), Error(`ESX: Component is not a valid component`))
58 | throws(() => init({ Component: [] }), Error(`ESX: Component is not a valid component`))
59 | doesNotThrow(() => init({ Component: Symbol('test') }))
60 | doesNotThrow(() => init({ Component: () => {} }))
61 | doesNotThrow(() => init({ Component: class {} }))
62 | doesNotThrow(() => init({ Component: { $$typeof: Symbol('test') } }))
63 | doesNotThrow(() => init({ Component: 'div' }))
64 | })
65 |
66 | test('register: components object values must be function,classes,symbols,strings or objects with a $$typeof key', async ({ throws, doesNotThrow }) => {
67 | throws(() => init().register({ Component: undefined }), Error(`ESX: Component is not a valid component`))
68 | throws(() => init().register({ Component: null }), Error(`ESX: Component is not a valid component`))
69 | throws(() => init().register({ Component: 1 }), Error(`ESX: Component is not a valid component`))
70 | throws(() => init().register({ Component: {} }), Error(`ESX: Component is not a valid component`))
71 | throws(() => init().register({ Component: [] }), Error(`ESX: Component is not a valid component`))
72 | doesNotThrow(() => init().register({ Component: Symbol('test') }))
73 | doesNotThrow(() => init().register({ Component: () => {} }))
74 | doesNotThrow(() => init().register({ Component: class {} }))
75 | doesNotThrow(() => init().register({ Component: { $$typeof: Symbol('test') } }))
76 | doesNotThrow(() => init().register({ Component: 'div' }))
77 | })
78 |
79 | test('register.lax: skips validation', async ({ doesNotThrow }) => {
80 | doesNotThrow(() => init().register.lax({ Component: undefined }))
81 | doesNotThrow(() => init().register.lax({ Component: null }))
82 | doesNotThrow(() => init().register.lax({ Component: 1 }))
83 | doesNotThrow(() => init().register.lax({ Component: {} }))
84 | doesNotThrow(() => init().register.lax({ Component: [] }))
85 | doesNotThrow(() => init().register.lax({ Component: Symbol('test') }))
86 | doesNotThrow(() => init().register.lax({ Component: () => {} }))
87 | doesNotThrow(() => init().register.lax({ Component: class {} }))
88 | doesNotThrow(() => init().register.lax({ Component: { $$typeof: Symbol('test') } }))
89 | doesNotThrow(() => init().register.lax({ Component: 'div' }))
90 | })
91 |
92 | test('register.one: components object values must be function,classes,symbols,strings or objects with a $$typeof key', async ({ throws, doesNotThrow }) => {
93 | throws(() => init().register.one('Component', undefined), Error(`ESX: Component is not a valid component`))
94 | throws(() => init().register.one('Component', null), Error(`ESX: Component is not a valid component`))
95 | throws(() => init().register.one('Component', 1), Error(`ESX: Component is not a valid component`))
96 | throws(() => init().register.one('Component', {}), Error(`ESX: Component is not a valid component`))
97 | throws(() => init().register.one('Component', []), Error(`ESX: Component is not a valid component`))
98 | doesNotThrow(() => init().register.one('Component', Symbol('test')))
99 | doesNotThrow(() => init().register.one('Component', () => {}))
100 | doesNotThrow(() => init().register.one('Component', class {}))
101 | doesNotThrow(() => init().register.one('Component', { $$typeof: Symbol('test') }))
102 | doesNotThrow(() => init().register.one('Component', 'div'))
103 | })
104 |
105 | test('register.one.lax: skips validation', async ({ doesNotThrow }) => {
106 | doesNotThrow(() => init().register.one.lax('Component', undefined))
107 | doesNotThrow(() => init().register.one.lax('Component', null))
108 | doesNotThrow(() => init().register.one.lax('Component', 'str'))
109 | doesNotThrow(() => init().register.one.lax('Component', 1))
110 | doesNotThrow(() => init().register.one.lax('Component', {}))
111 | doesNotThrow(() => init().register.one.lax('Component', []))
112 | doesNotThrow(() => init().register.one.lax('Component', Symbol('test')))
113 | doesNotThrow(() => init().register.one.lax('Component', () => {}))
114 | doesNotThrow(() => init().register.one.lax('Component', class {}))
115 | doesNotThrow(() => init().register.one.lax('Component', { $$typeof: Symbol('test') }))
116 | })
117 |
118 | test('all registrations throws if any component is using legacy context API', async ({ throws }) => {
119 | const esx = init()
120 | // simulate react-router 4 Link
121 | class Link extends React.Component {
122 | render () {
123 | return esx``
124 | }
125 | }
126 |
127 | Link.contextTypes = {
128 | router: PropTypes.shape({
129 | history: PropTypes.shape({
130 | push: PropTypes.func.isRequired,
131 | replace: PropTypes.func.isRequired,
132 | createHref: PropTypes.func.isRequired
133 | }).isRequired
134 | }).isRequired
135 | }
136 | const err = Error(`ESX: Link has a contextTypes property. Legacy context API is not supported – https://reactjs.org/docs/legacy-context.html`)
137 | throws(() => { init({ Link }) }, err)
138 | throws(() => { esx.register({ Link }) }, err)
139 | throws(() => { esx.register.lax({ Link }) }, err)
140 | throws(() => { esx.register.one('Link', Link) }, err)
141 | throws(() => { esx.register.one.lax('Link', Link) }, err)
142 | })
143 |
144 | test('empty string returns null', async ({ same }) => {
145 | const esx = init()
146 | same(render(esx``), null)
147 | })
148 |
149 | test('text at the root is ignored, returns null', async ({ same }) => {
150 | const esx = init()
151 | same(render(esx`ignore me`), null)
152 | })
153 |
154 | test('text outside elements is ignored', async ({ same }) => {
155 | const esx = init()
156 | same(render(esx`ignore me
`), render(createElement('hr'))) 162 | }) 163 | 164 | test('element and text child', async ({ same }) => { 165 | const esx = init() 166 | same(render(esx`![]()
`
257 | }
258 | esx.register({ Component })
259 | render(esx`![]()
`.props.b, 'y')
269 | is(esx`![]()
`.props.b, 'z')
270 | is(esx`![]()
`.props.b, 'z')
271 | is(esx`![]()
`.props.b, 'z')
272 | is(esx`![]()
`.props.b, 'y')
273 | })
274 |
275 | test('spread: props', async ({ is }) => {
276 | const esx = init()
277 | const { props } = esx`![]()
`
278 | const { a, b } = props
279 | is(a, 1)
280 | is(b, 2)
281 | })
282 |
283 | test('spread: props overwrite prior static props when collision', async ({ is }) => {
284 | const esx = init()
285 | const { props } = esx`![]()
`
286 | const { a, b, x } = props
287 | is(a, 1)
288 | is(b, 2)
289 | is(x, 'y')
290 | })
291 |
292 | test('spread: props overwrite prior dynamic props when collision', async ({ is }) => {
293 | const esx = init()
294 | const { props } = esx`![]()
`
295 | const { a, b } = props
296 | is(a, 1)
297 | is(b, 2)
298 | })
299 |
300 | test('spread: props preserve prior static props when no collision', async ({ is }) => {
301 | const esx = init()
302 | const { props } = esx`![]()
`
303 | const { a, b, x } = props
304 | is(a, 1)
305 | is(b, 2)
306 | is(x, 'keep')
307 | })
308 |
309 | test('spread: props preserve prior dynamic props when no collision', async ({ is }) => {
310 | const esx = init()
311 | const { props } = esx`![]()
`
312 | const { a, b, x } = props
313 | is(a, 1)
314 | is(b, 2)
315 | is(x, 'keep')
316 | })
317 |
318 | test('spread: props overwritten with latter static props', async ({ is }) => {
319 | const esx = init()
320 | const { props } = esx`![]()
`
321 | const { a, b } = props
322 | is(a, 1)
323 | is(b, 'x')
324 | })
325 |
326 | test('spread: props overwritten with latter dynamic props', async ({ is }) => {
327 | const esx = init()
328 | const { props } = esx`![]()
`
329 | const { a, b } = props
330 | is(a, 1)
331 | is(b, 'x')
332 | })
333 |
334 | test('spread: latest prop wins', async ({ is }) => {
335 | const esx = init()
336 | const { props } = esx`![]()
`
337 | const { a, b } = props
338 | is(a, 1)
339 | is(b, 'y')
340 | })
341 |
342 | test('spread: multiple objects', async ({ is }) => {
343 | const esx = init()
344 | const { props } = esx`![]()
`
345 | const { a, b, c, d } = props
346 | is(a, 1)
347 | is(b, 2)
348 | is(c, 3)
349 | is(d, 4)
350 | })
351 |
352 | test('spread: multiple objects, later object properties override', async ({ is }) => {
353 | const esx = init()
354 | const { props } = esx`![]()
`
355 | const { a, b } = props
356 | is(a, 3)
357 | is(b, 4)
358 | })
359 |
360 | test('spread: multiple objects, static props between spreads', async ({ is }) => {
361 | const esx = init()
362 | const { props } = esx`![]()
`
363 | const { a, b, x } = props
364 | is(a, 3)
365 | is(b, 4)
366 | is(x, 'y')
367 | })
368 |
369 | test('spread: multiple objects, dynamic props between spreads', async ({ is }) => {
370 | const esx = init()
371 | const { props } = esx`![]()
`
372 | const { a, b, x } = props
373 | is(a, 3)
374 | is(b, 4)
375 | is(x, 'y')
376 | })
377 |
378 | test('spread: multiple objects, duplicate dynamic props between spreads overriden by last spread', async ({ is }) => {
379 | const esx = init()
380 | const { props } = esx`![]()
`
381 | const { a, b } = props
382 | is(a, 3)
383 | is(b, 4)
384 | })
385 |
386 | test('children: deep element-nested dynamic + inline children', async ({ same }) => {
387 | const esx = init()
388 | const value = 'dynamic'
389 | const ESXComponent = () => esx`
439 | hi
440 | woop
441 |
442 | `
443 | const ReactCmp = () => {
444 | return createElement(Fragment, null, [
445 | createElement('head', null, createElement('title', null, 'hi')),
446 | createElement('body', null, 'woop')
447 | ])
448 | }
449 | esx.register({ EsxCmp, Fragment })
450 | same(
451 | render(esx`
460 | hi
461 | woop
462 |
463 | `
464 | const ReactCmp = () => {
465 | return createElement(React.Fragment, null, [
466 | createElement('head', null, createElement('title', null, 'hi')),
467 | createElement('body', null, 'woop')
468 | ])
469 | }
470 | esx.register({ EsxCmp })
471 | same(
472 | render(esx`hi
482 | woop
483 |
484 | `
485 | const ReactCmp = () => {
486 | return createElement(React.Fragment, null, [
487 | createElement('head', null, createElement('title', null, 'hi')),
488 | createElement('body', null, 'woop')
489 | ])
490 | }
491 | esx.register({ EsxCmp })
492 | same(
493 | render(esx`
503 | hi
504 | woop
505 |
506 | `
507 | const ReactCmp = () => {
508 | return createElement(Fragment, null, [
509 | createElement('head', null, createElement('title', null, 'hi')),
510 | createElement('body', null, 'woop')
511 | ])
512 | }
513 | esx.register({ EsxCmp, Fragment })
514 | same(
515 | render(esx`![]()
`), render(createElement('img', { className: 'x' })))
538 | same(render(esx`![]()
`), render(createElement('img', { className: 'x' })))
539 | })
540 |
541 | test('unexpected token, expression in open element', async ({ throws }) => {
542 | const esx = init()
543 | throws(() => esx`
`, SyntaxError('ESX: Unexpected token in element. Expressions may only be spread, embedded in attributes be included as children.'))
544 | })
545 |
546 | test('unexpected token, quotes around expression', async ({ throws }) => {
547 | const esx = init()
548 | throws(
549 | () => esx``,
550 | SyntaxError('Unexpected token. Attribute expressions must not be surrounded in quotes.')
551 | )
552 | })
553 |
554 | test('void elements must not have children', async ({ throws }) => {
555 | const esx = init()
556 | throws(() => esx`` and `
133 |
142 | `
143 | }
144 | }
145 | const Header = ({ name }) => esx`-
135 | ${todos.map(todo => esx`
136 |
- ${todo} 137 | `)} 138 |
${name} List
` 146 | const Footer = props => esx`` 147 | 148 | esx.register({ Header, Footer }) 149 | 150 | module.exports = App 151 | ``` 152 | 153 | In a client entry point this can be rendered the usual way: 154 | 155 | ```js 156 | const App = require('./App') 157 | const container = document.getElementById('app') 158 | const { hydrate } = require('react-dom') // using hydrate because we have SSR 159 | const esx = require('esx')({ App }) 160 | hydrate(esx `
175 | ${esx.renderToString `
177 |
178 |
179 | `)
180 | }).listen(3000)
181 | ```
182 |
183 | ## API
184 |
185 | The `esx` module exports an initializer function, which
186 | returns a template string tag function.
187 |
188 | ### Initializer: `createEsx(components = {}) => esx`
189 |
190 | The default export is a function that when called initializes an
191 | instance of `esx`.
192 |
193 | ```js
194 | import createEsx from 'esx'
195 | ```
196 |
197 | ```js
198 | const createEsx = require('esx')
199 | ```
200 |
201 | The initializer takes an object of component mappings which
202 | it then uses to look up component references within the template.
203 |
204 | When called, the Initializer returns a Template Engine instance.
205 |
206 | ### Template Engine: ``esx`test
`), render(createElement('p', null, 'test'))) 157 | }) 158 | 159 | test('element', async ({ same }) => { 160 | const esx = init() 161 | same(render(esx``), render(createElement('hr'))) 162 | }) 163 | 164 | test('element and text child', async ({ same }) => { 165 | const esx = init() 166 | same(render(esx`
hi
`), render(createElement('div', null, 'hi')))
167 | })
168 |
169 | test('interpolation', async ({ is }) => {
170 | const esx = init({})
171 | const value = 'test'
172 | const { type, props } = esx`
173 | ${value}
174 | `
175 | is(type, 'div')
176 | is(props.children, value)
177 | })
178 |
179 | test('function component', async ({ same }) => {
180 | const Component = () => esx`test
`
181 | const esx = init({ Component })
182 | same(render(esx`test
`
189 | }
190 | }
191 | const esx = init({ Component })
192 | same(render(esx`1
`
200 | }
201 | esx.register({ Component })
202 | same(
203 | render(esx`1
`),
204 | render(createElement('div', { x }, '1'))
205 | )
206 | })
207 |
208 | test('attr: function component props', async ({ same }) => {
209 | const Component = (props) => {
210 | return esx`${props.text}
`
211 | }
212 | const esx = init({ Component })
213 | const value = 'hi'
214 | same(
215 | render(esx`${props.text}
`
225 | }
226 | }
227 | const esx = init({ Component })
228 | const value = 'hi'
229 | same(render(esx`${state.text}
`
245 | }
246 | }
247 | const esx = init({ Component })
248 | same(render(esx`${value} inline
`
390 | const ReactComponent = () => React.createElement('div', null, [value, ' inline'])
391 | same(render(createElement(ESXComponent)), render(createElement(ReactComponent)))
392 | })
393 |
394 | test('children: deep inline children + element-nested dynamic', async ({ same }) => {
395 | const esx = init()
396 | const value = 'dynamic'
397 | const ESXComponent = () => esx`inline ${value}
`
398 | const ReactComponent = () => React.createElement('div', null, ['inline ', value])
399 | same(render(createElement(ESXComponent)), render(createElement(ReactComponent)))
400 | })
401 |
402 | test('nested components', async ({ same }) => {
403 | const esx = init()
404 | const Cmp2 = ({ text }) => {
405 | return esx`${text}
` 406 | } 407 | esx.register({ Cmp2 }) 408 | const Component = (props) => { 409 | return esx`${text}
` 421 | } 422 | esx.register({ Cmp2 }) 423 | const Cmp1 = (props) => { 424 | return esx`hi
hi
`, SyntaxError('ESX: Void elements must not have children or use dangerouslySetInnerHTML.'))
559 | esx.register({ Cmp () { return esx`hi
` } }) 560 | throws(() => esx`no' }}>
`, SyntaxError('ESX: Can only set one of children or dangerouslySetInnerHTML.'))
575 | throws(() => esx`no' }} children='no'>
`, SyntaxError('ESX: Can only set one of children or dangerouslySetInnerHTML.'))
576 | throws(() => esx`no' }}>${'no'}
`, SyntaxError('ESX: Can only set one of children or dangerouslySetInnerHTML.'))
577 | throws(() => esx`no' }}>no
`, SyntaxError('ESX: Can only set one of children or dangerouslySetInnerHTML.'))
578 | throws(() => esx`no' }} children='no'/>`, SyntaxError('ESX: Can only set one of children or dangerouslySetInnerHTML.'))
579 | throws(() => esx`
no' }} children=${'no'}/>`, SyntaxError('ESX: Can only set one of children or dangerouslySetInnerHTML.'))
580 | })
581 |
582 | test('unexpected token', async ({ throws }) => {
583 | const esx = init()
584 | const props = {}
585 | throws(() => esx``, SyntaxError('ESX: Unexpected token.'))
586 | })
587 |
588 | test('lack of component closing tag causes syntax error', async ({ throws }) => {
589 | const esx = init({ App: () => {} })
590 | throws(() => esx``, SyntaxError(`Expected corresponding ESX closing tag for `))
591 | throws(() => esx``))
592 | })
593 |
594 | test('lack of closing tag for elements other than auto closing elements causes syntax error', async ({ throws }) => {
595 | const esx = init({ App: () => {} })
596 | throws(() => esx`
`, SyntaxError(`Expected corresponding ESX closing tag for
`))
597 | throws(() => esx`
`, SyntaxError(`Expected corresponding ESX closing tag for
`))
598 | })
599 |
600 | test('lack of closing tag for auto closing elements does not throw', async ({ doesNotThrow }) => {
601 | const esx = init({ App: ({ children }) => children })
602 | doesNotThrow(() => esx``, SyntaxError(`Expected corresponding ESX closing tag for `))
603 | doesNotThrow(() => esx`
`, SyntaxError(`Expected corresponding ESX closing tag for
`)) 607 | doesNotThrow(() => esx`
`)) 608 | doesNotThrow(() => esx`
`, SyntaxError(`Expected corresponding ESX closing tag for
`)) 607 | doesNotThrow(() => esx`
`)) 608 | doesNotThrow(() => esx`