From 9b7ccc4ac0507b85fcdefb32c90a5526f888f7b0 Mon Sep 17 00:00:00 2001 From: Jolyn Date: Sun, 26 Oct 2025 23:50:56 -0600 Subject: [PATCH 1/6] Initial draft --- README.md | 50 +++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 49 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 205855f..3a3fbb4 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,50 @@ # compilation-import-attribute -A specification for an import attribute to differentiate kinds of imports + +A specification for an [import attribute](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import/with) to differentiate kinds of imports for Ecmascript compilers, bundlers, and runtimes. + +## Background + +Ecmascript imports can be processed in various environments, including browsers, NodeJS (or similar execution environments), compilers, or bundlers. When preprocessed with compilers or bundlers, Ecmascript imports have historically been configured to behave in at least three distinct ways: + +1. *Bundled:* the import is removed in favor of concatenating the imported files together into an output bundle +1. *Code split:* the import is processed as a separate bundle file (often called a "chunk") that is loaded dynamically at runtime, either through native `import()` or, more commonly, through a bundler-specific script load. The chunk itself is compiled as a bundle. +1. *Externalized:* the import is processed at runtime in the browser or NodeJS. + +In webpack, rollup, and other popular ecmascript bundlers, static `import` statements are processed by bundlers to be bundled, by default, whereas code splits are created via dynamic `import()` and externalized imports are configured within the bundler. Non-ecmascript bundlers, such as esbuild or swc, often follow similar conventions. + +## Problem Statement + +How an Ecmascript import statement behaves should be understood within the code itself, rather than a combination of the code and bundler configuration. An Ecmascript file should be self contained and portable regardless of which bundler, tooling, or configuration is present within a project. + +## Solution + +A `compilation` [import attribute](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import/with) allows the software developer to instruct compilers, bundlers, and preprocessors within the code itself, rather than in configuration. This allows the code to function regardless of which tooling, bundler, compiler, or configuration is changed in it. When the `compilation` import attribute is omitted, the bundler or compiler's default behavior is used. + +## Spec + +Compilers, bundlers, and/or their corresponding plugins support at least the following `compilation` import attributes: + +1. `ignore`: the import should be ignored by the compiler and remain intact, to be processed by the runtime execution environment (NodeJS, browser, etc). This is similar to webpack and rollup's `external` option. +1. `bundle`: the import should be removed and the corresponding code should be concatenated in as part of the current bundle. This is similar to webpack and rollup's default behavior for `import` statements +1. `split`: the import should remain intact, but the imported resource should undergo a compilation or bundling process rather than expect the resource to be provided by the runtime execution environment. This is similar to webpack and rollup's processing of dynamic `import()` as well as webpack's SplitChunksPlugin. + +## Examples + +A bundler, when given the following input: + +```js +import { useState } from 'react' with { compilation: "ignore" }; +import dayjs from 'dayjs' with { compilation: "bundle" }; +import { App } from './App' with { compilation: "split" }; +import { createBrowserRouter } from 'react-router'; +``` + +could produce the following output: + +```js +import { useState } from 'react'; +// dayjs concatenated into the bundle +import { App } from './app-chunk.js'; +// react-router concatenated into the bundle, as the default behavior when the compilation import attribute is missing +``` + From 703c9ae9b6d6d98ba7ba5304d7f82321de2cc3bf Mon Sep 17 00:00:00 2001 From: Jolyn Date: Sun, 26 Oct 2025 23:54:06 -0600 Subject: [PATCH 2/6] Self review --- README.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/README.md b/README.md index 3a3fbb4..a6c2a43 100644 --- a/README.md +++ b/README.md @@ -48,3 +48,16 @@ import { App } from './app-chunk.js'; // react-router concatenated into the bundle, as the default behavior when the compilation import attribute is missing ``` +Similarly, an input file with a dynamic import: + +```js +// Input +import('react', { with: { compilation: "ignore" } }); +``` + +is compiled to the following: + +```js +// Output +import('react'); +``` From 8e593aaf35d6802fa74f0294aef50baf4efcc089 Mon Sep 17 00:00:00 2001 From: Jolyn Date: Sun, 26 Oct 2025 23:59:39 -0600 Subject: [PATCH 3/6] Self review --- README.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/README.md b/README.md index a6c2a43..b9e1187 100644 --- a/README.md +++ b/README.md @@ -61,3 +61,13 @@ is compiled to the following: // Output import('react'); ``` + +## Support + +To support the `compilation` attribute, the following tooling will be created: + +- webpack plugin +- rollup plugin +- babel plugin +- something to make tsc understand it +- any tooling for esbuild, swc, vite, jest, etc From ff02587e9320cca1b5582e2c21ddd52d1c5a59bb Mon Sep 17 00:00:00 2001 From: Jolyn Date: Mon, 27 Oct 2025 00:01:38 -0600 Subject: [PATCH 4/6] Self review --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index b9e1187..2a381ea 100644 --- a/README.md +++ b/README.md @@ -69,5 +69,6 @@ To support the `compilation` attribute, the following tooling will be created: - webpack plugin - rollup plugin - babel plugin +- NodeJS loader - something to make tsc understand it - any tooling for esbuild, swc, vite, jest, etc From ea5ccc1cdf17087126449e1667792dc9ad04e05e Mon Sep 17 00:00:00 2001 From: Jolyn Date: Mon, 27 Oct 2025 00:12:43 -0600 Subject: [PATCH 5/6] Self review --- README.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 2a381ea..2a158c0 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,20 @@ # compilation-import-attribute -A specification for an [import attribute](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import/with) to differentiate kinds of imports for Ecmascript compilers, bundlers, and runtimes. +A specification for an [import attribute](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import/with) to differentiate kinds of imports for ECMAScript compilers, bundlers, and runtimes. ## Background -Ecmascript imports can be processed in various environments, including browsers, NodeJS (or similar execution environments), compilers, or bundlers. When preprocessed with compilers or bundlers, Ecmascript imports have historically been configured to behave in at least three distinct ways: +ECMAScript imports can be processed in various environments, including browsers, NodeJS (or similar execution environments), compilers, or bundlers. When preprocessed with compilers or bundlers, ECMAScript imports have historically been configured to behave in at least three distinct ways: 1. *Bundled:* the import is removed in favor of concatenating the imported files together into an output bundle 1. *Code split:* the import is processed as a separate bundle file (often called a "chunk") that is loaded dynamically at runtime, either through native `import()` or, more commonly, through a bundler-specific script load. The chunk itself is compiled as a bundle. 1. *Externalized:* the import is processed at runtime in the browser or NodeJS. -In webpack, rollup, and other popular ecmascript bundlers, static `import` statements are processed by bundlers to be bundled, by default, whereas code splits are created via dynamic `import()` and externalized imports are configured within the bundler. Non-ecmascript bundlers, such as esbuild or swc, often follow similar conventions. +In webpack, rollup, and other popular ECMAScript bundlers, static `import` statements are processed by bundlers to be bundled, by default, whereas code splits are created via dynamic `import()` and externalized imports are configured within the bundler. Non-ECMAScript bundlers, such as esbuild or swc, often follow similar conventions. ## Problem Statement -How an Ecmascript import statement behaves should be understood within the code itself, rather than a combination of the code and bundler configuration. An Ecmascript file should be self contained and portable regardless of which bundler, tooling, or configuration is present within a project. +How an ECMAScript import statement behaves should be understood within the code itself, rather than a combination of the code and bundler configuration. An ECMAScript file should be self contained and portable regardless of which bundler, tooling, or configuration is present within a project. ## Solution @@ -62,6 +62,12 @@ is compiled to the following: import('react'); ``` +## Benefits + +- There is tension between ECMAScript being an interpreted language but a lot of the source code requiring a compilation process before it can be interpreted. The `compilation` import attribute surfaces that tension within the source code rather than burying it within myriad configuration variants across the open source ecosystem. +- Any ECMAScript source code file could be statically analyzed for the `compilation` import attribute in order to know whether it is intended to be executed directly or first pre-processed by a compiler or bundler. +- Webpack's `import(/* webpackIgnore: true */)` special syntax for dynamic imports could be superseded by a syntax not tied to any specific bundler + ## Support To support the `compilation` attribute, the following tooling will be created: @@ -72,3 +78,5 @@ To support the `compilation` attribute, the following tooling will be created: - NodeJS loader - something to make tsc understand it - any tooling for esbuild, swc, vite, jest, etc + +Adding browser support for the `compilation` attribute would likely not be possible, as it is the runtime execution environment rather than a compiler or bundler From b76a8972b28c989a602994ec0dfc18f46f75beb6 Mon Sep 17 00:00:00 2001 From: Jolyn Date: Mon, 27 Oct 2025 00:34:15 -0600 Subject: [PATCH 6/6] Fix wording for clarity in README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 2a158c0..3a2dac5 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ In webpack, rollup, and other popular ECMAScript bundlers, static `import` state ## Problem Statement -How an ECMAScript import statement behaves should be understood within the code itself, rather than a combination of the code and bundler configuration. An ECMAScript file should be self contained and portable regardless of which bundler, tooling, or configuration is present within a project. +How an ECMAScript import statement behaves should be understood within the source code itself, rather than a combination of the code and bundler configuration. An ECMAScript file should be self contained and portable regardless of which bundler, tooling, or configuration is present within a project. ## Solution