feat(build)!: Introduce exports section in package.json (#7822)

* fix(typings): Remove bogus .d.ts files; add new languages
  
  PR #3821 added .d.ts files for every file in msg/json/, but several
  of these are internal utility files rather than translations, and
  do not result in a langfile being output by create_messages.py
  when building langfiles.
  
  In the meantime we have added a few new languages that are being
  published but which have (until now) not had the corresponding
  type declarations.
  
* feat(build)!: Add exports section to package.json
  
  Add an exports stanza to package.json, enumerating existing
  entrypoints in a new format.
  
  - The original main entrypoint, index.js, is removed since the
    exports section can point directly at node.js or browser.js.
  - No change made (yet) to other entrypoints (core, blocks,
    generators); these will be dealt with in a subsequent PR.
  - The msg/en entrypoint is included in the top-level package.json
    as an example; entries for all other languages created as part
    of the packageJSON package task.
  
  BREAKING CHANGE: The introduction of an exports stanza means that
  correctly-behaved tools (node.js, bundlers like webpack, etc.)
  will only allow importing of the specified entrypoints.  Here
  is the full list of permitted entrypoints that can be imported
  or required:
  
  - blockly
  - blockly/core
  - blockly/blocks
  - blockly/dart
  - blockly/lua
  - blockly/javascript
  - blockly/php
  - blockly/python
  - blockly/msg/<lang>, for all supported language codes <lang>
    (e.g blockly/msg/en, blockly/msg/fr, blockly/msg/de, etc.)
  
  If you previously impored any other paths from the blockly package
  you will need to update your imports.  Here are the most common
  paths that may have been used, and their correct replacements:
  
  | If you previously imported:      | Import instead:            |
  | -------------------------------- | -------------------------- |
  | blockly/index.js                 | blockly                    |
  | blockly/node.js                  | blockly                    |
  | blockly/browser.js               | blockly                    |
  | blockly/blockly.min | This file should only be loaded as a <script>. |
  | blockly/core.js                  | blockly/core               |
  | blockly/core-browser.js          | blockly/core               |
  | blockly/blockly_compressed.js    | blockly/core               |
  | blockly/blocks.js                | blockly/blocks             |
  | blockly/blocks_compressed.js     | blockly/blocks             |
  | blockly/dart.js                  | blockly/dart               |
  | blockly/dart_compressed.js       | blockly/dart               |
  | blockly/lua.js                   | blockly/lua                |
  | blockly/lua_compressed.js        | blockly/lua                |
  | blockly/javascript.js            | blockly/javascript         |
  | blockly/javascript_compressed.js | blockly/javascript         |
  | blockly/php.js                   | blockly/php                |
  | blockly/php_compressed.js        | blockly/php                |
  | blockly/python.js                | blockly/python             |
  | blockly/python_compressed.js     | blockly/python             |
  | blockly/msg/en.js                | blockly/msg/en             |
  
* fix(build): Use package-paths (blockly/*) in wrapper imports
  
  Use 'blockly/core' instead of './core' when importing core into
  other wrappers (and similarly for other entries in package.json
  exports stanza), so that (e.g.) dist/javascript.js won't
  import dist/core.js (the node.js version that loads jsdom) when
  being loaded in a browser environment.
  
  This fixes an issue where blockly attempts to load jsdom even
  in browser environments because the browser stanza in
  package.json, which caused attempts to load core.js to load
  core-browser.js instead in browser environments, was removed
  in a previous commit.
  
* refactor(build): Remove unnecessray wrappers
  
  Remove pointless wrapper modules that no longer server any
  purpose; use exports stanza in package.json to point directly to
  compiled chunks where possible.
  
* refactor(build)!: Eliminate separate browser and node entrypoints
  
  Combine scripts/package/browser/index.js (becomes dist/browser.js)
  and scripts/package/node/index.js (becomes dist/node.js) into
  a single environment-agnostic index.js.
  
  BREAKING CHANGE: Historically, importing the main 'blockly' package
  would import 'blockly/core', 'blockly/blocks', 'blockly/en' and
  'blockly/javascript' - and additionally, in node.js, also import
  'blockly/dart', 'blockly/lua', 'blockly/php' and 'blockly/python'.
  
  Now the main 'blockly' package entrypoint never loads any of the
  generator modules.
  
  This change has been made because of changes to generator exports
  made in blockly v9.0.0 that make necessary to always separately
  import generator modules.
  
  Note that this change does not affect loading the blockly package
  via <script src="https://unpkg.com/blockly"; that continues to
  load to blockly.min.js, which includes javascript_compressed.js
  and (due to being loaded as a script) makes it available via
  Blockly.JavaScript.
  
* refactor(build): Simplify core entrypoint wrapper for node.js
  
  Move scripts/package/node/core.js to scripts/package/core-node.js,
  and have it packaged as dist/core-node.js rather than dist/core.js
  - without a UMD wrapper, since it will always be loaded as a CJS
  module.
  
* chore(build): Remove disused packageCommonJS helper
  
* refactor(build): Use subpath pattern (wildcard) for msg/* exports
  
  Use a subpath pattern (wildcard) for the msg/* entrypoints,
  obviating the need for special handling in packageJSON.
  
* fix(tests): Fix node tests
  
  run_node_test.js previously directly require()d the dist/blockly.js
  and dist/javascript.js wrapper module, which no longer exist.
  
  Change it to require('blockly-test') (and …blockly-test/javascript)
  and create a symlink ./node_modules/blocky-test -> dist/ to satisfy
  this.
  
* fix(build): Add types: and default: entries to exports['./core']
  
  In the 'blockly/core' export:
  
  - Replace the browser: entrypoint with a default: one.
  - Add a types: entrypoint for core.

Author: cpcallen

package.json

@@ -54,14 +54,45 @@
     "test:compile:advanced": "gulp buildAdvancedCompilationTest --debug",
     "updateGithubPages": "npm ci && gulp gitUpdateGithubPages"
   },
-  "main": "./index.js",
-  "umd": "./blockly.min.js",
-  "unpkg": "./blockly.min.js",
-  "types": "./index.d.ts",
-  "browser": {
-    "./node.js": "./browser.js",
-    "./core.js": "./core-browser.js",
-    "./blockly-node.js": "./blockly.js"
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "umd": "./blockly.min.js",
+      "default": "./index.js"
+    },
+    "./core": {
+      "types": "./core.d.ts",
+      "node": "./core-node.js",
+      "default": "./blockly_compressed.js"
+    },
+    "./blocks": {
+      "types": "./blocks.d.ts",
+      "default": "./blocks_compressed.js"
+    },
+    "./dart": {
+      "types": "./dart.d.ts",
+      "default": "./dart_compressed.js"
+    },
+    "./lua": {
+      "types": "./lua.d.ts",
+      "default": "./lua_compressed.js"
+    },
+    "./javascript": {
+      "types": "./javascript.d.ts",
+      "default": "./javascript_compressed.js"
+    },
+    "./php": {
+      "types": "./php.d.ts",
+      "default": "./php_compressed.js"
+    },
+    "./python": {
+      "types": "./python.d.ts",
+      "default": "./python_compressed.js"
+    },
+    "./msg/*": {
+      "types": "./msg/*.d.ts",
+      "default": "./msg/*.js"
+    }
   },
   "license": "Apache-2.0",
   "devDependencies": {

scripts/gulpfiles/build_tasks.js

@@ -23,7 +23,7 @@ const closureCompiler = require('google-closure-compiler').gulp();
 const argv = require('yargs').argv;
 const {rimraf} = require('rimraf');
 
-const {BUILD_DIR, RELEASE_DIR, TSC_OUTPUT_DIR, TYPINGS_BUILD_DIR} = require('./config');
+const {BUILD_DIR, LANG_BUILD_DIR, RELEASE_DIR, TSC_OUTPUT_DIR, TYPINGS_BUILD_DIR} = require('./config');
 const {getPackageJson} = require('./helper_tasks');
 
 const {posixPath, quote} = require('../helpers');
@@ -350,8 +350,7 @@ this removal!
  */
 function buildLangfiles(done) {
   // Create output directory.
-  const outputDir = path.join(BUILD_DIR, 'msg');
-  fs.mkdirSync(outputDir, {recursive: true});
+  fs.mkdirSync(LANG_BUILD_DIR, {recursive: true});
 
   // Run create_messages.py.
   let json_files = fs.readdirSync(path.join('msg', 'json'));
@@ -364,7 +363,7 @@ function buildLangfiles(done) {
   --source_synonym_file ${path.join('msg', 'json', 'synonyms.json')} \
   --source_constants_file ${path.join('msg', 'json', 'constants.json')} \
   --key_file ${path.join('msg', 'json', 'keys.json')} \
-  --output_dir ${outputDir} \
+  --output_dir ${LANG_BUILD_DIR} \
   --quiet ${json_files.join(' ')}`;
   execSync(createMessagesCmd, {stdio: 'inherit'});
 

scripts/gulpfiles/config.js

@@ -26,6 +26,9 @@ exports.BUILD_DIR = 'build';
 // Directory to write typings output to.
 exports.TYPINGS_BUILD_DIR = path.join(exports.BUILD_DIR, 'declarations');
 
+// Directory to write langfile output to.
+exports.LANG_BUILD_DIR = path.join(exports.BUILD_DIR, 'msg');
+
 // Directory where typescript compiler output can be found.
 // Matches the value in tsconfig.json: outDir
 exports.TSC_OUTPUT_DIR = path.join(exports.BUILD_DIR, 'src');