Skip to content

Commit

Permalink
Consolidate JavaScript Flavors (facebook#1433)
Browse files Browse the repository at this point in the history
Summary:
Fixes facebook#1417

This dramatically simplifies the matrix of Node vs web, ASM vs WASM, sync vs async compilation, or CommonJS vs ES Modules. We have one variant, using wasm, with ESModule top-level await to do async compilation. Web/node share the same binary, and we base64 encode the WASM into a wrapper JS file for compatibility with Node and bundlers.

This has some downsides, like requiring an environment with top level await, but also has upsides, like a consistent, sync looking API compatible with older Yoga, and mitigating TypeScript issues with package exports and typings resolution.

As part of this work I also removed `ts-node` from the toolchain (at the cost of a couple of config files needing to be vanilla JS).

Pull Request resolved: facebook#1433

Test Plan:
1. `yarn test`
2. `yarn lint`
3. `yarn tsc`
4. `yarn benchmark`
5. `yarn build` website-next
6. `yarn lint` website-next
7. Locally test website-next
8. Examine package artifact created by GitHub
9. All Automation passes

Reviewed By: yungsters

Differential Revision: D50453324

Pulled By: NickGerleman

fbshipit-source-id: fe1192acc69e57fa69a1ff056dd7b5844d2198d5
  • Loading branch information
NickGerleman authored and facebook-github-bot committed Nov 1, 2023
1 parent b19a07c commit ef1d772
Show file tree
Hide file tree
Showing 68 changed files with 853 additions and 2,394 deletions.
88 changes: 88 additions & 0 deletions .eslintrc.cjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
/**
* Copyright (c) Meta Platforms, Inc. and affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @format
*/

module.exports = {
root: true,
ignorePatterns: [
'/website',
'**/binaries/**',
'**/build/**',
'**/generated/**',
],
overrides: [
// Catch-all
{
files: ['**/*.?(m|c){j,t}s?(x)'],
extends: ['eslint:recommended', 'plugin:prettier/recommended'],
plugins: ['prettier'],
rules: {
'no-unused-vars': ['error', {argsIgnorePattern: '^_'}],
'no-var': 'error',
'prefer-arrow-callback': 'error',
'prefer-const': 'error',
'prefer-object-spread': 'error',
'prefer-spread': 'error',
'require-await': 'error',
},
env: {
es2020: true,
},
parserOptions: {
ecmaVersion: 'latest',
},
},
// ES Modules
{
files: ['**/*.?(m){j,t}s?(x)'],
parserOptions: {
sourceType: 'module',
},
},
// CommonJS Modules
{
files: ['**/*.c{j,t}s?(x)'],
env: {
commonjs: true,
},
parserOptions: {
sourceType: 'commonjs',
},
},
// TypeScript
{
files: ['**/*.?(m|c)ts?(x)'],
extends: ['plugin:@typescript-eslint/recommended'],
parser: '@typescript-eslint/parser',
parserOptions: {
project: true,
},
plugins: ['@typescript-eslint'],
rules: {
'@typescript-eslint/ban-ts-comment': 'off',
'@typescript-eslint/no-unused-vars': [
'error',
{argsIgnorePattern: '^_'},
],
'@typescript-eslint/no-var-requires': 'off',
},
},
// Node
{
files: ['**/.*rc.(c){j,t}s', '**/*.config.?(c){j,t}s'],
env: {
node: true,
},
},
// Jest
{
files: ['**/tests/**'],
extends: ['plugin:jest/recommended'],
},
],
};
76 changes: 0 additions & 76 deletions .eslintrc.js

This file was deleted.

2 changes: 1 addition & 1 deletion gentest/gentest-javascript.js
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ JavascriptEmitter.prototype = Object.create(Emitter.prototype, {

emitPrologue: {
value: function () {
this.push('import {Yoga} from "../tools/globals";');
this.push("import Yoga from 'yoga-layout';");
this.push('import {');
this.pushIndent();
this.push('Align,');
Expand Down
76 changes: 12 additions & 64 deletions javascript/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -31,9 +31,9 @@ add_compile_options(${COMPILE_OPTIONS})

add_link_options(
${COMPILE_OPTIONS}
--closure 1
--memory-init-file 0
--no-entry
"SHELL:--closure 1"
"SHELL:--memory-init-file 0"
"SHELL:--no-entry"
"SHELL:-s ALLOW_MEMORY_GROWTH=1"
"SHELL:-s ASSERTIONS=0"
"SHELL:-s DYNAMIC_EXECUTION=0"
Expand All @@ -42,71 +42,19 @@ add_link_options(
"SHELL:-s FILESYSTEM=0"
"SHELL:-s MALLOC='emmalloc'"
"SHELL:-s MODULARIZE=1"
"SHELL:-s TEXTDECODER=0"
"SHELL:-s SINGLE_FILE=1")
"SHELL:-s EXPORT_ES6=1"
"SHELL:-s WASM=1"
"SHELL:-s TEXTDECODER=0")

link_libraries(embind)

add_library(yogaObjLib OBJECT ${SOURCES})

set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/binaries)

add_executable(asmjs-sync-node $<TARGET_OBJECTS:yogaObjLib>)
target_link_options(asmjs-sync-node PUBLIC
"SHELL:-s ENVIRONMENT='node'"
"SHELL:-s WASM=0"
"SHELL:-s WASM_ASYNC_COMPILATION=0")

add_executable(asmjs-async-node $<TARGET_OBJECTS:yogaObjLib>)
target_link_options(asmjs-async-node PUBLIC
"SHELL:-s ENVIRONMENT='node'"
"SHELL:-s WASM=0"
"SHELL:-s WASM_ASYNC_COMPILATION=1")

add_executable(asmjs-sync-web $<TARGET_OBJECTS:yogaObjLib>)
target_link_options(asmjs-sync-web PUBLIC
"SHELL:-s ENVIRONMENT='web'"
"SHELL:-s WASM=0"
"SHELL:-s WASM_ASYNC_COMPILATION=0")

add_executable(asmjs-async-web $<TARGET_OBJECTS:yogaObjLib>)
target_link_options(asmjs-async-web PUBLIC
"SHELL:-s ENVIRONMENT='web'"
"SHELL:-s WASM=0"
"SHELL:-s WASM_ASYNC_COMPILATION=1")

add_executable(asmjs-sync $<TARGET_OBJECTS:yogaObjLib>)
target_link_options(asmjs-sync PUBLIC
"SHELL:-s ENVIRONMENT='web,node'"
"SHELL:-s WASM=0"
"SHELL:-s WASM_ASYNC_COMPILATION=0")

add_executable(asmjs-async $<TARGET_OBJECTS:yogaObjLib>)
target_link_options(asmjs-async PUBLIC
"SHELL:-s ENVIRONMENT='web,node'"
"SHELL:-s WASM=0"
"SHELL:-s WASM_ASYNC_COMPILATION=1")

add_executable(wasm-sync-node $<TARGET_OBJECTS:yogaObjLib>)
target_link_options(wasm-sync-node PUBLIC
"SHELL:-s ENVIRONMENT='node'"
"SHELL:-s WASM=1"
"SHELL:-s WASM_ASYNC_COMPILATION=0")

add_executable(wasm-async-node $<TARGET_OBJECTS:yogaObjLib>)
target_link_options(wasm-async-node PUBLIC
"SHELL:-s ENVIRONMENT='node'"
"SHELL:-s WASM=1"
"SHELL:-s WASM_ASYNC_COMPILATION=1")

add_executable(wasm-sync-web $<TARGET_OBJECTS:yogaObjLib>)
target_link_options(wasm-sync-web PUBLIC
"SHELL:-s ENVIRONMENT='web'"
"SHELL:-s WASM=1"
"SHELL:-s WASM_ASYNC_COMPILATION=0")

add_executable(wasm-async-web $<TARGET_OBJECTS:yogaObjLib>)
target_link_options(wasm-async-web PUBLIC
"SHELL:-s ENVIRONMENT='web'"
"SHELL:-s WASM=1"
"SHELL:-s WASM_ASYNC_COMPILATION=1")
add_executable(web $<TARGET_OBJECTS:yogaObjLib>)
target_link_options(web PRIVATE
# SINGLE_FILE=1 combined with ENVIRONMENT='web' creates code that works on
# both bundlders and Node.
"SHELL:-s SINGLE_FILE=1"
"SHELL:-s ENVIRONMENT='web'")
31 changes: 6 additions & 25 deletions javascript/README.md
Original file line number Diff line number Diff line change
@@ -1,24 +1,11 @@
# yoga-layout

This package provides prebuilt JavaScript bindings for the Yoga layout engine. Both WebAssembly and asm.js variants are packaged, with the optimal loaded based on platform.
This package provides prebuilt WebAssembly bindings for the Yoga layout engine.

## Usage

The default entrypoint provides an asynchronous loader function to return a Yoga instance.

```ts
import {loadYoga, Align} from 'yoga-layout';

const Yoga = await loadYoga();

const node = Yoga.Node.create();
node.setAlignContent(Align.Center);
```

An alternative synchronous API is provided for compatibility, but requires using asm.js in browsers instead of WebAssembly, leading to worse performance and larger assets.

```ts
import Yoga, {Align} from 'yoga-layout/sync';
import {Yoga, Align} from 'yoga-layout';

const node = Yoga.Node.create();
node.setAlignContent(Align.Center);
Expand All @@ -37,20 +24,14 @@ node.freeRecursive();
node.free();
```

## Selecting WebAssembly or asm.js

For better performance and smaller packages, WebAssembly is preferred to asm.js where available. `yoga-layout` tries to provide the right default using [export maps](https://webpack.js.org/guides/package-exports/#conditional-syntax) so that platforms which can take advantage of WebAssembly use it by default.

Different entrypoints are exposed to choose a flavor explicitly.

```ts
import {loadYoga} from 'yoga-layout/wasm-async';
```

## Using TypeScript

This package provides out-of-the-box TypeScript typings so long as `tsc` is configured to support ESM resolution. It is recommended to set `moduleResolution: 'bundler'` or `moduleResolution: node16` in your `tsconfig.json` according to your environment.

## ES Modules

`yoga-layout` is only provided as an ES Module, relying on top-level await. This allows providing a synchronous API, while still allowing async WebAssembly compilation in browsers, and will allow eventual usage of ESM/WASM interop.

## Contributing

### Requirements
Expand Down
30 changes: 30 additions & 0 deletions javascript/babel.config.cjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
/**
* Copyright (c) Meta Platforms, Inc. and affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*
* @format
*/

module.exports = api => ({
presets: [
[
'@babel/preset-env',
{
targets: [
'maintained node versions',
'> 0.5%, last 2 versions, Firefox ESR, not dead',
],
// Do not transform to another module system
modules: false,
},
],
[
'@babel/preset-typescript',
{
rewriteImportExtensions: api.env('dist'),
},
],
],
});
9 changes: 4 additions & 5 deletions javascript/.babelrc.js → javascript/jest.config.js
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,8 @@
* @format
*/

module.exports = {
presets: [
['@babel/preset-env', {targets: 'defaults'}],
'@babel/preset-typescript',
],
export default {
setupFiles: ['./jest.setup.js'],
testRegex: '/tests/.*\\.test\\.ts$',
extensionsToTreatAsEsm: ['.ts'],
};
27 changes: 0 additions & 27 deletions javascript/jest.config.ts

This file was deleted.

Loading

0 comments on commit ef1d772

Please sign in to comment.