From 88548ac339b41b1e37b89a70d2add2e64c5c908d Mon Sep 17 00:00:00 2001
From: Owen Buckley <owenbuckley13@gmail.com>
Date: Thu, 5 Sep 2024 13:37:12 -0400
Subject: [PATCH] feature/issue 1268 import map and attribute polyfill
 configuration (#1269)

* import map polyfill config flag

* import attributes polyfill config option

* import attributes demo

* develop test cases for import maps and attributes for development

* import attributes polyfill config serve test cases

* polyfills configuration error test cases

* bundle polyfilled import attributes for the browser

* polyfills configuration docs and import attributes call outs

* misc refactoring

* add acorn-import-attributes as a CLI dependency

* refine pre-intercepting logic to include all JS resource types

* remove demo code

* more robust bundling and serve test case
---
 packages/cli/package.json                     |   1 +
 packages/cli/src/config/rollup.config.js      |  40 +++-
 packages/cli/src/lifecycles/config.js         |  31 ++-
 packages/cli/src/lifecycles/prerender.js      |  12 +-
 packages/cli/src/loader.js                    |   3 +-
 .../plugins/resource/plugin-node-modules.js   |  11 +-
 .../plugins/resource/plugin-standard-css.js   |   4 +-
 .../resource/plugin-standard-javascript.js    |  38 ++++
 .../plugins/resource/plugin-standard-json.js  |   5 +-
 ...g.error-polyfill-import-attributes.spec.js |  51 +++++
 .../greenwood.config.js                       |   5 +
 ....config.error-polyfill-import-maps.spec.js |  51 +++++
 .../greenwood.config.js                       |   5 +
 .../develop.config.base-path.spec.js          |   2 +-
 ...config.polyfills-import-attributes.spec.js | 185 ++++++++++++++++++
 .../greenwood.config.js                       |   5 +
 .../package.json                              |   4 +
 .../src/components/hero.css                   |   3 +
 .../src/components/hero.js                    |  54 +++++
 .../src/components/hero.json                  |   3 +
 .../src/index.html                            |  11 ++
 .../src/theme.css                             |   3 +
 ...velop.config.polyfills-import-maps.spec.js | 126 ++++++++++++
 .../greenwood.config.js                       |   5 +
 .../package.json                              |   4 +
 .../src/components/hero.js                    |  64 ++++++
 .../src/index.html                            |  11 ++
 .../develop.default/develop.default.spec.js   |  11 +-
 .../greenwood.config.js                       |   6 +
 ...config.polyfills-import-attributes.spec.js | 178 +++++++++++++++++
 .../src/components/hero.css                   |   3 +
 .../src/components/hero.js                    |  33 ++++
 .../src/components/hero.json                  |   3 +
 .../src/index.html                            |  11 ++
 .../src/theme.css                             |   3 +
 .../develop.default/develop.default.spec.js   |   2 +-
 packages/plugin-import-raw/src/index.js       |   5 +-
 .../develop.default/develop.default.spec.js   |   6 +-
 packages/plugin-renderer-lit/src/index.js     |  10 +-
 www/pages/docs/configuration.md               |  57 +++++-
 www/pages/docs/css-and-images.md              |   2 +
 www/pages/docs/scripts.md                     |   6 +-
 42 files changed, 1017 insertions(+), 56 deletions(-)
 create mode 100644 packages/cli/test/cases/build.config.error-polyfill-import-attributes/build.config.error-polyfill-import-attributes.spec.js
 create mode 100644 packages/cli/test/cases/build.config.error-polyfill-import-attributes/greenwood.config.js
 create mode 100644 packages/cli/test/cases/build.config.error-polyfill-import-maps/build.config.error-polyfill-import-maps.spec.js
 create mode 100644 packages/cli/test/cases/build.config.error-polyfill-import-maps/greenwood.config.js
 create mode 100644 packages/cli/test/cases/develop.config.polyfills-import-attributes/develop.config.polyfills-import-attributes.spec.js
 create mode 100644 packages/cli/test/cases/develop.config.polyfills-import-attributes/greenwood.config.js
 create mode 100644 packages/cli/test/cases/develop.config.polyfills-import-attributes/package.json
 create mode 100644 packages/cli/test/cases/develop.config.polyfills-import-attributes/src/components/hero.css
 create mode 100644 packages/cli/test/cases/develop.config.polyfills-import-attributes/src/components/hero.js
 create mode 100644 packages/cli/test/cases/develop.config.polyfills-import-attributes/src/components/hero.json
 create mode 100644 packages/cli/test/cases/develop.config.polyfills-import-attributes/src/index.html
 create mode 100644 packages/cli/test/cases/develop.config.polyfills-import-attributes/src/theme.css
 create mode 100644 packages/cli/test/cases/develop.config.polyfills-import-maps/develop.config.polyfills-import-maps.spec.js
 create mode 100644 packages/cli/test/cases/develop.config.polyfills-import-maps/greenwood.config.js
 create mode 100644 packages/cli/test/cases/develop.config.polyfills-import-maps/package.json
 create mode 100644 packages/cli/test/cases/develop.config.polyfills-import-maps/src/components/hero.js
 create mode 100644 packages/cli/test/cases/develop.config.polyfills-import-maps/src/index.html
 create mode 100644 packages/cli/test/cases/loaders-serve.config.polyfill-import-attributes/greenwood.config.js
 create mode 100644 packages/cli/test/cases/loaders-serve.config.polyfill-import-attributes/loaders-serve.config.polyfills-import-attributes.spec.js
 create mode 100644 packages/cli/test/cases/loaders-serve.config.polyfill-import-attributes/src/components/hero.css
 create mode 100644 packages/cli/test/cases/loaders-serve.config.polyfill-import-attributes/src/components/hero.js
 create mode 100644 packages/cli/test/cases/loaders-serve.config.polyfill-import-attributes/src/components/hero.json
 create mode 100644 packages/cli/test/cases/loaders-serve.config.polyfill-import-attributes/src/index.html
 create mode 100644 packages/cli/test/cases/loaders-serve.config.polyfill-import-attributes/src/theme.css

diff --git a/packages/cli/package.json b/packages/cli/package.json
index 4f1751425..3cc14d85b 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -35,6 +35,7 @@
     "@rollup/plugin-replace": "^5.0.5",
     "@rollup/plugin-terser": "^0.4.4",
     "acorn": "^8.0.1",
+    "acorn-import-attributes": "^1.9.5",
     "acorn-walk": "^8.0.0",
     "commander": "^2.20.0",
     "css-tree": "^2.2.1",
diff --git a/packages/cli/src/config/rollup.config.js b/packages/cli/src/config/rollup.config.js
index e50e2aa61..53734d8e7 100644
--- a/packages/cli/src/config/rollup.config.js
+++ b/packages/cli/src/config/rollup.config.js
@@ -16,6 +16,7 @@ function cleanRollupId(id) {
 const externalizedResources = ['css', 'json'];
 
 function greenwoodResourceLoader (compilation, browser = false) {
+  const { importAttributes } = compilation.config?.polyfills;
   const resourcePlugins = compilation.config.plugins.filter((plugin) => {
     return plugin.type === 'resource';
   }).map((plugin) => {
@@ -33,7 +34,10 @@ function greenwoodResourceLoader (compilation, browser = false) {
       if (normalizedId.startsWith('.')) {
         const importerUrl = new URL(normalizedId, `file://${importer}`);
         const extension = importerUrl.pathname.split('.').pop();
-        const external = externalizedResources.includes(extension) && browser && !importerUrl.searchParams.has('type');
+        // if we are polyfilling import attributes for the browser we will want Rollup to bundles these as JS files
+        // instead of externalizing as their native content-type
+        const shouldPolyfill = browser && (importAttributes || []).includes(extension);
+        const external = !shouldPolyfill && externalizedResources.includes(extension) && browser && !importerUrl.searchParams.has('type');
         const isUserWorkspaceUrl = importerUrl.pathname.startsWith(userWorkspace.pathname);
         const prefix = normalizedId.startsWith('..') ? './' : '';
         // if its not in the users workspace, we clean up the dot-dots and check that against the user's workspace
@@ -54,8 +58,7 @@ function greenwoodResourceLoader (compilation, browser = false) {
       const { pathname } = idUrl;
       const extension = pathname.split('.').pop();
       const headers = {
-        'Accept': 'text/javascript',
-        'Sec-Fetch-Dest': 'empty'
+        'Accept': 'text/javascript'
       };
 
       // filter first for any bare specifiers
@@ -254,8 +257,7 @@ function greenwoodImportMetaUrl(compilation) {
       const normalizedId = id.replace(/\\\\/g, '/').replace(/\\/g, '/'); // windows shenanigans...
       let idUrl = new URL(`file://${cleanRollupId(id)}`);
       const headers = {
-        'Accept': 'text/javascript',
-        'Sec-Fetch-Dest': 'empty'
+        'Accept': 'text/javascript'
       };
       const request = new Request(idUrl, {
         headers
@@ -424,7 +426,8 @@ function greenwoodImportMetaUrl(compilation) {
 // - sync externalized import attribute paths with bundled CSS paths
 function greenwoodSyncImportAttributes(compilation) {
   const unbundledAssetsRefMapper = {};
-  const { basePath } = compilation.config;
+  const { basePath, polyfills } = compilation.config;
+  const { importAttributes } = polyfills;
 
   return {
     name: 'greenwood-sync-import-attributes',
@@ -451,7 +454,16 @@ function greenwoodSyncImportAttributes(compilation) {
             if (externalizedResources.includes(extension)) {
               let preBundled = false;
               let inlineOptimization = false;
-              bundles[bundle].code = bundles[bundle].code.replace(/assert{/g, 'with{');
+
+              if (importAttributes && importAttributes.includes(extension)) {
+                importAttributes.forEach((attribute) => {
+                  if (attribute === extension) {
+                    bundles[bundle].code = bundles[bundle].code.replace(new RegExp(`"assert{type:"${attribute}"}`, 'g'), `?polyfill=type-${extension}"`);
+                  }
+                });
+              } else {
+                bundles[bundle].code = bundles[bundle].code.replace(/assert{/g, 'with{');
+              }
 
               // check for app level assets, like say a shared theme.css
               compilation.resources.forEach((resource) => {
@@ -529,9 +541,17 @@ function greenwoodSyncImportAttributes(compilation) {
               // have to apply Greenwood's optimizing here instead of in generateBundle
               // since we can't do async work inside a sync AST operation
               if (!asset.preBundled) {
-                const assetUrl = unbundledAssetsRefMapper[asset].sourceURL;
-                const request = new Request(assetUrl, { headers: { 'Accept': 'text/css' } });
-                let response = new Response(unbundledAssetsRefMapper[asset].source, { headers: { 'Content-Type': 'text/css' } });
+                const type = ext === 'css'
+                  ? 'text/css'
+                  : ext === 'css'
+                    ? 'application/json'
+                    : '';
+                const assetUrl = importAttributes && importAttributes.includes(ext)
+                  ? new URL(`${unbundledAssetsRefMapper[asset].sourceURL.href}?polyfill=type-${ext}`)
+                  : unbundledAssetsRefMapper[asset].sourceURL;
+
+                const request = new Request(assetUrl, { headers: { 'Accept': type } });
+                let response = new Response(unbundledAssetsRefMapper[asset].source, { headers: { 'Content-Type': type } });
 
                 for (const plugin of resourcePlugins) {
                   if (plugin.shouldPreIntercept && await plugin.shouldPreIntercept(assetUrl, request, response.clone())) {
diff --git a/packages/cli/src/lifecycles/config.js b/packages/cli/src/lifecycles/config.js
index 7ee7fc2f7..9c31a230a 100644
--- a/packages/cli/src/lifecycles/config.js
+++ b/packages/cli/src/lifecycles/config.js
@@ -52,7 +52,11 @@ const defaultConfig = {
   prerender: false,
   isolation: false,
   pagesDirectory: 'pages',
-  layoutsDirectory: 'layouts'
+  layoutsDirectory: 'layouts',
+  polyfills: {
+    importAttributes: null, // or ['css', 'json']
+    importMaps: false
+  }
 };
 
 const readAndMergeConfig = async() => {
@@ -77,7 +81,8 @@ const readAndMergeConfig = async() => {
 
       if (hasConfigFile) {
         const userCfgFile = (await import(configUrl)).default;
-        const { workspace, devServer, markdown, optimization, plugins, port, prerender, basePath, staticRouter, pagesDirectory, layoutsDirectory, interpolateFrontmatter, isolation } = userCfgFile;
+        // eslint-disable-next-line max-len
+        const { workspace, devServer, markdown, optimization, plugins, port, prerender, basePath, staticRouter, pagesDirectory, layoutsDirectory, interpolateFrontmatter, isolation, polyfills } = userCfgFile;
 
         // workspace validation
         if (workspace) {
@@ -239,6 +244,28 @@ const readAndMergeConfig = async() => {
             reject(`Error: greenwood.config.js staticRouter must be a boolean; true or false.  Passed value was typeof: ${typeof staticRouter}`);
           }
         }
+
+        if (polyfills !== undefined) {
+          const { importMaps, importAttributes } = polyfills;
+
+          customConfig.polyfills = {};
+
+          if (importMaps) {
+            if (typeof importMaps === 'boolean') {
+              customConfig.polyfills.importMaps = true;
+            } else {
+              reject(`Error: greenwood.config.js polyfills.importMaps must be a boolean; true or false.  Passed value was typeof: ${typeof importMaps}`);
+            }
+          }
+
+          if (importAttributes) {
+            if (Array.isArray(importAttributes)) {
+              customConfig.polyfills.importAttributes = importAttributes;
+            } else {
+              reject(`Error: greenwood.config.js polyfills.importAttributes must be an array of types; ['css', 'json'].  Passed value was typeof: ${typeof importAttributes}`);
+            }
+          }
+        }
       } else {
         // SPA should _not_ prerender unless if user has specified prerender should be true
         if (isSPA) {
diff --git a/packages/cli/src/lifecycles/prerender.js b/packages/cli/src/lifecycles/prerender.js
index 04007e00e..67994a345 100644
--- a/packages/cli/src/lifecycles/prerender.js
+++ b/packages/cli/src/lifecycles/prerender.js
@@ -121,6 +121,7 @@ async function preRenderCompilationWorker(compilation, workerPrerender) {
 async function preRenderCompilationCustom(compilation, customPrerender) {
   const { scratchDir } = compilation.context;
   const renderer = (await import(customPrerender.customUrl)).default;
+  const { importMaps } = compilation.config.polyfills;
 
   console.info('pages to generate', `\n ${compilation.graph.map(page => page.route).join('\n ')}`);
 
@@ -129,10 +130,13 @@ async function preRenderCompilationCustom(compilation, customPrerender) {
     const outputPathUrl = new URL(`.${outputPath}`, scratchDir);
 
     // clean up special Greenwood dev only assets that would come through if prerendering with a headless browser
-    body = body.replace(/<script src="(.*lit\/polyfill-support.js)"><\/script>/, '');
-    body = body.replace(/<script type="importmap-shim">.*?<\/script>/s, '');
-    body = body.replace(/<script defer="" src="(.*es-module-shims.js)"><\/script>/, '');
-    body = body.replace(/type="module-shim"/g, 'type="module"');
+    if (importMaps) {
+      body = body.replace(/<script type="importmap-shim">.*?<\/script>/s, '');
+      body = body.replace(/<script defer="" src="(.*es-module-shims.js)"><\/script>/, '');
+      body = body.replace(/type="module-shim"/g, 'type="module"');
+    } else {
+      body = body.replace(/<script type="importmap">.*?<\/script>/s, '');
+    }
 
     // clean this up to avoid sending webcomponents-bundle to rollup
     body = body.replace(/<script src="(.*webcomponents-bundle.js)"><\/script>/, '');
diff --git a/packages/cli/src/loader.js b/packages/cli/src/loader.js
index 792f43c43..9a676ff2f 100644
--- a/packages/cli/src/loader.js
+++ b/packages/cli/src/loader.js
@@ -19,8 +19,7 @@ const resourcePlugins = config.plugins
 
 async function getCustomLoaderResponse(initUrl, checkOnly = false) {
   const headers = {
-    'Accept': 'text/javascript',
-    'Sec-Fetch-Dest': 'empty'
+    'Accept': 'text/javascript'
   };
   const initResponse = new Response('');
   let request = new Request(initUrl, { headers });
diff --git a/packages/cli/src/plugins/resource/plugin-node-modules.js b/packages/cli/src/plugins/resource/plugin-node-modules.js
index ff05c4446..286c2de08 100644
--- a/packages/cli/src/plugins/resource/plugin-node-modules.js
+++ b/packages/cli/src/plugins/resource/plugin-node-modules.js
@@ -73,11 +73,14 @@ class NodeModulesResource extends ResourceInterface {
   }
 
   async intercept(url, request, response) {
-    const { context } = this.compilation;
+    const { context, config } = this.compilation;
+    const { importMaps } = config.polyfills;
+    const importMapType = importMaps ? 'importmap-shim' : 'importmap';
+    const importMapShimScript = importMaps ? '<script defer src="/node_modules/es-module-shims/dist/es-module-shims.js"></script>' : '';
     let body = await response.text();
     const hasHead = body.match(/\<head>(.*)<\/head>/s);
 
-    if (hasHead && hasHead.length > 0) {
+    if (importMaps && hasHead && hasHead.length > 0) {
       const contents = hasHead[0].replace(/type="module"/g, 'type="module-shim"');
 
       body = body.replace(/\<head>(.*)<\/head>/s, contents.replace(/\$/g, '$$$')); // https://github.com/ProjectEvergreen/greenwood/issues/656);
@@ -97,8 +100,8 @@ class NodeModulesResource extends ResourceInterface {
     // apply import map and shim for users
     body = body.replace('<head>', `
       <head>
-        <script defer src="/node_modules/es-module-shims/dist/es-module-shims.js"></script>
-        <script type="importmap-shim">
+        ${importMapShimScript}
+        <script type="${importMapType}">
           {
             "imports": ${JSON.stringify(importMap, null, 1)}
           }
diff --git a/packages/cli/src/plugins/resource/plugin-standard-css.js b/packages/cli/src/plugins/resource/plugin-standard-css.js
index 27bfbcee0..d6985494d 100644
--- a/packages/cli/src/plugins/resource/plugin-standard-css.js
+++ b/packages/cli/src/plugins/resource/plugin-standard-css.js
@@ -312,14 +312,14 @@ class StandardCssResource extends ResourceInterface {
 
     return url.protocol === 'file:'
       && ext === this.extensions[0]
-      && (response.headers.get('Content-Type')?.indexOf('text/css') >= 0 || request.headers.get('Accept')?.indexOf('text/javascript') >= 0);
+      && (response.headers.get('Content-Type')?.indexOf('text/css') >= 0 || request.headers.get('Accept')?.indexOf('text/javascript') >= 0) || url.searchParams?.get('polyfill') === 'type-css';
   }
 
   async intercept(url, request, response) {
     let body = bundleCss(await response.text(), url, this.compilation);
     let headers = {};
 
-    if (request.headers.get('Accept')?.indexOf('text/javascript') >= 0 && !url.searchParams.has('type')) {
+    if ((request.headers.get('Accept')?.indexOf('text/javascript') >= 0 || url.searchParams?.get('polyfill') === 'type-css') && !url.searchParams.has('type')) {
       const contents = body.replace(/\r?\n|\r/g, ' ').replace(/\\/g, '\\\\');
 
       body = `const sheet = new CSSStyleSheet();sheet.replaceSync(\`${contents}\`);export default sheet;`;
diff --git a/packages/cli/src/plugins/resource/plugin-standard-javascript.js b/packages/cli/src/plugins/resource/plugin-standard-javascript.js
index 820899a4e..ec013bc07 100644
--- a/packages/cli/src/plugins/resource/plugin-standard-javascript.js
+++ b/packages/cli/src/plugins/resource/plugin-standard-javascript.js
@@ -7,6 +7,9 @@
 import fs from 'fs/promises';
 import { ResourceInterface } from '../../lib/resource-interface.js';
 import terser from '@rollup/plugin-terser';
+import * as acorn from 'acorn';
+import * as walk from 'acorn-walk';
+import { importAttributes } from 'acorn-import-attributes';
 
 class StandardJavaScriptResource extends ResourceInterface {
   constructor(compilation, options) {
@@ -28,6 +31,41 @@ class StandardJavaScriptResource extends ResourceInterface {
       }
     });
   }
+
+  async shouldPreIntercept(url, request, response) {
+    const { polyfills } = this.compilation.config;
+
+    return (polyfills?.importAttributes || []).length > 0 && url.protocol === 'file:' && response.headers.get('Content-Type').indexOf(this.contentType) >= 0;
+  }
+
+  async preIntercept(url, request, response) {
+    const { polyfills } = this.compilation.config;
+    const body = await response.clone().text();
+    let polyfilled = body;
+
+    walk.simple(acorn.Parser.extend(importAttributes).parse(body, {
+      ecmaVersion: 'latest',
+      sourceType: 'module'
+    }), {
+      async ImportDeclaration(node) {
+        const line = body.slice(node.start, node.end);
+        const { value } = node.source;
+
+        polyfills.importAttributes.forEach((attribute) => {
+          if (line.replace(/ /g, '').replace(/"/g, '\'').includes(`with{type:'${attribute}'}`)) {
+            polyfilled = polyfilled.replace(line, `${line.split('with')[0]};\n`);
+            polyfilled = polyfilled.replace(value, `${value}?polyfill=type-${attribute}`);
+          }
+        });
+      }
+    });
+
+    return new Response(polyfilled, {
+      headers: {
+        'Content-Type': this.contentType
+      }
+    });
+  }
 }
 
 const greenwoodPluginStandardJavascript = [{
diff --git a/packages/cli/src/plugins/resource/plugin-standard-json.js b/packages/cli/src/plugins/resource/plugin-standard-json.js
index 07d9883aa..0610eb7ca 100644
--- a/packages/cli/src/plugins/resource/plugin-standard-json.js
+++ b/packages/cli/src/plugins/resource/plugin-standard-json.js
@@ -45,7 +45,10 @@ class StandardJsonResource extends ResourceInterface {
     const { protocol, pathname, searchParams } = url;
     const ext = pathname.split('.').pop();
 
-    return protocol === 'file:' && request.headers.get('Accept')?.indexOf('text/javascript') >= 0 && ext === this.extensions[0] && !searchParams.has('type');
+    return protocol === 'file:'
+      && ext === this.extensions[0]
+      && !searchParams.has('type')
+      && (request.headers.get('Accept')?.indexOf('text/javascript') >= 0 || url.searchParams?.get('polyfill') === 'type-json');
   }
 
   async intercept(url, request, response) {
diff --git a/packages/cli/test/cases/build.config.error-polyfill-import-attributes/build.config.error-polyfill-import-attributes.spec.js b/packages/cli/test/cases/build.config.error-polyfill-import-attributes/build.config.error-polyfill-import-attributes.spec.js
new file mode 100644
index 000000000..8bd1197d8
--- /dev/null
+++ b/packages/cli/test/cases/build.config.error-polyfill-import-attributes/build.config.error-polyfill-import-attributes.spec.js
@@ -0,0 +1,51 @@
+/*
+ * Use Case
+ * Run Greenwood build command with a bad value for polyfill.importAttributes in a custom config.
+ *
+ * User Result
+ * Should throw an error.
+ *
+ * User Command
+ * greenwood build
+ *
+ * User Config
+ * {
+ *   polyfills: {
+ *     importAttributes: {}
+ *   }
+ * }
+ *
+ * User Workspace
+ * Greenwood default
+ */
+import chai from 'chai';
+import path from 'path';
+import { Runner } from 'gallinago';
+import { fileURLToPath, URL } from 'url';
+
+const expect = chai.expect;
+
+describe('Build Greenwood With: ', function() {
+  const cliPath = path.join(process.cwd(), 'packages/cli/src/index.js');
+  const outputPath = fileURLToPath(new URL('.', import.meta.url));
+  let runner;
+
+  before(function() {
+    this.context = {
+      publicDir: path.join(outputPath, 'public')
+    };
+    runner = new Runner();
+  });
+
+  describe('Custom Configuration with a bad value for Polyfills w/ Import Attributes', function() {
+    it('should throw an error that polyfills.importAttributes must be an array of types; [\'css\', \'json\']', function() {
+      try {
+        runner.setup(outputPath);
+        runner.runCommand(cliPath, 'build');
+      } catch (err) {
+        expect(err).to.contain('Error: greenwood.config.js polyfill.importAttributes must be a an array of types; [\'css\', \'json\'].  Passed value was typeof: object');
+      }
+    });
+  });
+
+});
\ No newline at end of file
diff --git a/packages/cli/test/cases/build.config.error-polyfill-import-attributes/greenwood.config.js b/packages/cli/test/cases/build.config.error-polyfill-import-attributes/greenwood.config.js
new file mode 100644
index 000000000..6bdd19bc5
--- /dev/null
+++ b/packages/cli/test/cases/build.config.error-polyfill-import-attributes/greenwood.config.js
@@ -0,0 +1,5 @@
+export default {
+  polyfills: {
+    importAttributes: null
+  }
+};
\ No newline at end of file
diff --git a/packages/cli/test/cases/build.config.error-polyfill-import-maps/build.config.error-polyfill-import-maps.spec.js b/packages/cli/test/cases/build.config.error-polyfill-import-maps/build.config.error-polyfill-import-maps.spec.js
new file mode 100644
index 000000000..e9c9cbfb7
--- /dev/null
+++ b/packages/cli/test/cases/build.config.error-polyfill-import-maps/build.config.error-polyfill-import-maps.spec.js
@@ -0,0 +1,51 @@
+/*
+ * Use Case
+ * Run Greenwood build command with a bad value for polyfill.importMaps in a custom config.
+ *
+ * User Result
+ * Should throw an error.
+ *
+ * User Command
+ * greenwood build
+ *
+ * User Config
+ * {
+ *   polyfills: {
+ *     importMaps: {}
+ *   }
+ * }
+ *
+ * User Workspace
+ * Greenwood default
+ */
+import chai from 'chai';
+import path from 'path';
+import { Runner } from 'gallinago';
+import { fileURLToPath, URL } from 'url';
+
+const expect = chai.expect;
+
+describe('Build Greenwood With: ', function() {
+  const cliPath = path.join(process.cwd(), 'packages/cli/src/index.js');
+  const outputPath = fileURLToPath(new URL('.', import.meta.url));
+  let runner;
+
+  before(function() {
+    this.context = {
+      publicDir: path.join(outputPath, 'public')
+    };
+    runner = new Runner();
+  });
+
+  describe('Custom Configuration with a bad value for Polyfills w/ Import Maps', function() {
+    it('should throw an error that polyfill.importMaps must be a boolean', function() {
+      try {
+        runner.setup(outputPath);
+        runner.runCommand(cliPath, 'build');
+      } catch (err) {
+        expect(err).to.contain('Error: greenwood.config.js polyfill.importMaps must be a boolean; true or false.  Passed value was typeof: object');
+      }
+    });
+  });
+
+});
\ No newline at end of file
diff --git a/packages/cli/test/cases/build.config.error-polyfill-import-maps/greenwood.config.js b/packages/cli/test/cases/build.config.error-polyfill-import-maps/greenwood.config.js
new file mode 100644
index 000000000..8eb55f402
--- /dev/null
+++ b/packages/cli/test/cases/build.config.error-polyfill-import-maps/greenwood.config.js
@@ -0,0 +1,5 @@
+export default {
+  polyfills: {
+    importMaps: {}
+  }
+};
\ No newline at end of file
diff --git a/packages/cli/test/cases/develop.config.base-path/develop.config.base-path.spec.js b/packages/cli/test/cases/develop.config.base-path/develop.config.base-path.spec.js
index 64e3d9ff9..e939b86d2 100644
--- a/packages/cli/test/cases/develop.config.base-path/develop.config.base-path.spec.js
+++ b/packages/cli/test/cases/develop.config.base-path/develop.config.base-path.spec.js
@@ -1,6 +1,6 @@
 /*
  * Use Case
- * Run Greenwood serve command with no basePath configuration set (and staticRouter).
+ * Run Greenwood develop command with no basePath configuration set (and staticRouter).
  *
  * User Result
  * Should start the development server and render a the Greenwood application.
diff --git a/packages/cli/test/cases/develop.config.polyfills-import-attributes/develop.config.polyfills-import-attributes.spec.js b/packages/cli/test/cases/develop.config.polyfills-import-attributes/develop.config.polyfills-import-attributes.spec.js
new file mode 100644
index 000000000..a4cf8af94
--- /dev/null
+++ b/packages/cli/test/cases/develop.config.polyfills-import-attributes/develop.config.polyfills-import-attributes.spec.js
@@ -0,0 +1,185 @@
+/*
+ * Use Case
+ * Run Greenwood develop command with import attributes polyfill flag enabled.
+ *
+ * User Result
+ * Should start the development server and have all the expected import attributes polyfill behaviors.
+ *
+ * User Command
+ * greenwood develop
+ *
+ * User Config
+ * polyfill: {
+ *   importAttributes: ['css', 'json']
+ * }
+ *
+ * User Workspace
+ * src/
+ *   components/
+ *     hero.js
+ *     hero.css
+ *     hero.json
+ *   index.html
+ *   theme.css
+ * greenwood.config.js
+ * package.json
+ *
+ */
+import chai from 'chai';
+import path from 'path';
+import { getSetupFiles } from '../../../../../test/utils.js';
+import { Runner } from 'gallinago';
+import { fileURLToPath, URL } from 'url';
+
+const expect = chai.expect;
+
+describe('Develop Greenwood With: ', function() {
+  const LABEL = 'Import Attributes Polyfill Configuration';
+  const cliPath = path.join(process.cwd(), 'packages/cli/src/index.js');
+  const outputPath = fileURLToPath(new URL('.', import.meta.url));
+  const hostname = 'http://localhost';
+  const port = 1984;
+  let runner;
+
+  before(function() {
+    this.context = {
+      hostname: `${hostname}:${port}`
+    };
+    runner = new Runner();
+  });
+
+  describe(LABEL, function() {
+
+    before(async function() {
+
+      runner.setup(outputPath, [
+        ...getSetupFiles(outputPath)
+      ]);
+
+      return new Promise((resolve) => {
+        setTimeout(() => {
+          resolve();
+        }, 5000);
+
+        runner.runCommand(cliPath, 'develop', { async: true });
+      });
+    });
+
+    describe('Import Attributes Polyfill Behaviors for the initiating JavaScript file (hero.js)', function() {
+      let response = {};
+      let text;
+
+      before(async function() {
+        response = await fetch(`${hostname}:${port}/components/hero.js`, {
+          headers: {
+            accept: 'text/html'
+          }
+        });
+
+        text = await response.clone().text();
+      });
+
+      it('should return the correct content type', function(done) {
+        expect(response.headers.get('content-type')).to.contain('text/javascript');
+        done();
+      });
+
+      it('should return a 200', function(done) {
+        expect(response.status).to.equal(200);
+
+        done();
+      });
+
+      it('should not contain import attributes syntax', function(done) {
+        expect(text.replace(/ /g, '')).to.not.contain('with{type:');
+
+        done();
+      });
+
+      it('should contain import attributes polyfill syntax for CSS files', function(done) {
+        expect(text.replace(/ /g, '')).to.contain('importsheetfrom\'./hero.css?polyfill=type-css\'');
+        expect(text.replace(/ /g, '')).to.contain('importthemefrom\'../theme.css?polyfill=type-css\'');
+
+        done();
+      });
+
+      it('should contain import attributes polyfill syntax for JSON', function(done) {
+        expect(text.replace(/ /g, '')).to.contain('importjsonfrom\'./hero.json?polyfill=type-json\'');
+
+        done();
+      });
+    });
+
+    describe('Import Attributes Polyfill Behavior for CSS', function() {
+      let response = {};
+      let text;
+
+      before(async function() {
+        response = await fetch(`${hostname}:${port}/components/hero.css?polyfill=type-css`, {
+          headers: {
+            accept: 'text/html'
+          }
+        });
+
+        text = await response.clone().text();
+      });
+
+      it('should return the correct content type', function(done) {
+        expect(response.headers.get('content-type')).to.contain('text/javascript');
+        done();
+      });
+
+      it('should return a 200', function(done) {
+        expect(response.status).to.equal(200);
+
+        done();
+      });
+
+      it('should return the contents as an exported Constructable StyleSheet ES module', function(done) {
+        expect(text).to.equal('const sheet = new CSSStyleSheet();sheet.replaceSync(`:host h2{font-size:3em}`);export default sheet;');
+
+        done();
+      });
+    });
+
+    describe('Import Attributes Polyfill Behavior for JSON', function() {
+      let response = {};
+      let text;
+
+      before(async function() {
+        response = await fetch(`${hostname}:${port}/components/hero.json?polyfill=type-json`, {
+          headers: {
+            accept: 'text/html'
+          }
+        });
+
+        text = await response.clone().text();
+      });
+
+      it('should return the correct content type', function(done) {
+        expect(response.headers.get('content-type')).to.contain('text/javascript');
+        done();
+      });
+
+      it('should return a 200', function(done) {
+        expect(response.status).to.equal(200);
+
+        done();
+      });
+
+      it('should return the contents as an exported Constructable StyleSheet ES module', function(done) {
+        expect(text).to.equal('export default {"msg":"Hello World"}');
+
+        done();
+      });
+    });
+  });
+
+  after(function() {
+    runner.stopCommand();
+    runner.teardown([
+      path.join(outputPath, '.greenwood'),
+      path.join(outputPath, 'node_modules')
+    ]);
+  });
+});
\ No newline at end of file
diff --git a/packages/cli/test/cases/develop.config.polyfills-import-attributes/greenwood.config.js b/packages/cli/test/cases/develop.config.polyfills-import-attributes/greenwood.config.js
new file mode 100644
index 000000000..2e7968463
--- /dev/null
+++ b/packages/cli/test/cases/develop.config.polyfills-import-attributes/greenwood.config.js
@@ -0,0 +1,5 @@
+export default {
+  polyfills: {
+    importAttributes: ['css', 'json']
+  }
+};
\ No newline at end of file
diff --git a/packages/cli/test/cases/develop.config.polyfills-import-attributes/package.json b/packages/cli/test/cases/develop.config.polyfills-import-attributes/package.json
new file mode 100644
index 000000000..2623a52e3
--- /dev/null
+++ b/packages/cli/test/cases/develop.config.polyfills-import-attributes/package.json
@@ -0,0 +1,4 @@
+{
+  "name": "test-develop-command-config-import-attributes",
+  "type": "module"
+}
\ No newline at end of file
diff --git a/packages/cli/test/cases/develop.config.polyfills-import-attributes/src/components/hero.css b/packages/cli/test/cases/develop.config.polyfills-import-attributes/src/components/hero.css
new file mode 100644
index 000000000..cbc4a27e7
--- /dev/null
+++ b/packages/cli/test/cases/develop.config.polyfills-import-attributes/src/components/hero.css
@@ -0,0 +1,3 @@
+:host h2 {
+  font-size: 3em;
+}
\ No newline at end of file
diff --git a/packages/cli/test/cases/develop.config.polyfills-import-attributes/src/components/hero.js b/packages/cli/test/cases/develop.config.polyfills-import-attributes/src/components/hero.js
new file mode 100644
index 000000000..64004d157
--- /dev/null
+++ b/packages/cli/test/cases/develop.config.polyfills-import-attributes/src/components/hero.js
@@ -0,0 +1,54 @@
+// intentionally break formatting to validate our AST parsing is not impacted / naive
+import sheet from './hero.css'
+with { type: 'css' }; // eslint-disable-line indent
+import theme from '../theme.css' with { type: 'css' };
+import json from './hero.json'
+  with { type: 'json' };
+
+const template = document.createElement('template');
+
+template.innerHTML = `
+  <div class="hero">
+    <h2>Welcome to my website</h2>
+    
+    <a href="#">
+      <button>Get Started</button>
+    </a>
+    <a href="#">
+      <button>Learn More &#8594</button>
+    </a>
+
+  </div>
+`;
+
+export default class HeroBanner extends HTMLElement {
+  clickButton(el) {
+    const content = el.textContent;
+    const buttonClickedEvent = new CustomEvent('update-modal', {
+      detail: {
+        content: `You selected "${content}"`
+      }
+    });
+
+    console.log('clicked button =>', content);
+
+    window.dispatchEvent(buttonClickedEvent);
+  }
+
+  connectedCallback() {
+    console.log({ sheet, json });
+
+    if (!this.shadowRoot) {
+      this.attachShadow({ mode: 'open' });
+      this.shadowRoot.appendChild(template.content.cloneNode(true));
+    }
+
+    this.shadowRoot.adoptedStyleSheets = [theme, sheet];
+    this.shadowRoot.querySelectorAll('button')
+      .forEach(button => {
+        button.addEventListener('click', () => this.clickButton(button));
+      });
+  }
+}
+
+customElements.define('app-hero', HeroBanner);
\ No newline at end of file
diff --git a/packages/cli/test/cases/develop.config.polyfills-import-attributes/src/components/hero.json b/packages/cli/test/cases/develop.config.polyfills-import-attributes/src/components/hero.json
new file mode 100644
index 000000000..45437a894
--- /dev/null
+++ b/packages/cli/test/cases/develop.config.polyfills-import-attributes/src/components/hero.json
@@ -0,0 +1,3 @@
+{
+  "msg": "Hello World"
+}
\ No newline at end of file
diff --git a/packages/cli/test/cases/develop.config.polyfills-import-attributes/src/index.html b/packages/cli/test/cases/develop.config.polyfills-import-attributes/src/index.html
new file mode 100644
index 000000000..87e929b43
--- /dev/null
+++ b/packages/cli/test/cases/develop.config.polyfills-import-attributes/src/index.html
@@ -0,0 +1,11 @@
+<html>
+
+  <head>
+    <script type="module" src="./components/hero.js"></script>
+  </head>
+
+  <body>
+    <app-hero></app-hero>
+  </body>
+  
+</html>
\ No newline at end of file
diff --git a/packages/cli/test/cases/develop.config.polyfills-import-attributes/src/theme.css b/packages/cli/test/cases/develop.config.polyfills-import-attributes/src/theme.css
new file mode 100644
index 000000000..0f7c63922
--- /dev/null
+++ b/packages/cli/test/cases/develop.config.polyfills-import-attributes/src/theme.css
@@ -0,0 +1,3 @@
+a {
+  color: blue;
+}
\ No newline at end of file
diff --git a/packages/cli/test/cases/develop.config.polyfills-import-maps/develop.config.polyfills-import-maps.spec.js b/packages/cli/test/cases/develop.config.polyfills-import-maps/develop.config.polyfills-import-maps.spec.js
new file mode 100644
index 000000000..4a7bda62b
--- /dev/null
+++ b/packages/cli/test/cases/develop.config.polyfills-import-maps/develop.config.polyfills-import-maps.spec.js
@@ -0,0 +1,126 @@
+/*
+ * Use Case
+ * Run Greenwood develop command with import maps polyfill flag enabled.
+ *
+ * User Result
+ * Should start the development server and have all the expected import map shim behaviors.
+ *
+ * User Command
+ * greenwood develop
+ *
+ * User Config
+ * devServer: {
+ *   polyfill: {
+ *     importMaps: true
+ *   }
+ * }
+ *
+ * User Workspace
+ * src/
+ *   components/
+ *     hero.js
+ *   index.html
+ * greenwood.config.js
+ * package.json
+ */
+import chai from 'chai';
+import { JSDOM } from 'jsdom';
+import path from 'path';
+import { getSetupFiles } from '../../../../../test/utils.js';
+import { Runner } from 'gallinago';
+import { fileURLToPath, URL } from 'url';
+
+const expect = chai.expect;
+
+describe('Develop Greenwood With: ', function() {
+  const LABEL = 'Import Maps Polyfill Configuration';
+  const cliPath = path.join(process.cwd(), 'packages/cli/src/index.js');
+  const outputPath = fileURLToPath(new URL('.', import.meta.url));
+  const hostname = 'http://localhost';
+  const port = 1984;
+  let runner;
+
+  before(function() {
+    this.context = {
+      hostname: `${hostname}:${port}`
+    };
+    runner = new Runner();
+  });
+
+  describe(LABEL, function() {
+
+    before(async function() {
+
+      runner.setup(outputPath, [
+        ...getSetupFiles(outputPath)
+      ]);
+
+      return new Promise((resolve) => {
+        setTimeout(() => {
+          resolve();
+        }, 5000);
+
+        runner.runCommand(cliPath, 'develop', { async: true });
+      });
+    });
+
+    describe('Import Map Shim Behaviors', function() {
+      let response = {};
+      let dom;
+
+      before(async function() {
+        response = await fetch(`${hostname}:${port}/`, {
+          headers: {
+            accept: 'text/html'
+          }
+        });
+
+        dom = new JSDOM(await response.clone().text());
+      });
+
+      it('should return the correct content type', function(done) {
+        expect(response.headers.get('content-type')).to.contain('text/html');
+        done();
+      });
+
+      it('should return a 200', function(done) {
+        expect(response.status).to.equal(200);
+
+        done();
+      });
+
+      // <script type="importmap-shim">{ "imports": {} }</script>
+      it('should have a shim-ed importmaps <script> tag in the <head> tag', function(done) {
+        const scriptTags = Array.from(dom.window.document.querySelectorAll('head > script[type="importmap-shim"'));
+
+        expect(scriptTags.length).to.equal(1);
+        done();
+      });
+
+      // <script defer src="/node_modules/es-module-shims/dist/es-module-shims.js"></script>
+      it('should have a <script> tag for loading the shim library', function(done) {
+        const scriptTags = Array.from(dom.window.document.querySelectorAll('head > script[src*="node_modules/es-module-shims"'));
+
+        expect(scriptTags.length).to.equal(1);
+        done();
+      });
+
+      // <script type="module-shim" src="./components/hero.js"></script>
+      it('should have a shim-ed <script> tag for the <app-hero> tag', function(done) {
+        const scriptTags = Array.from(dom.window.document.querySelectorAll('head > script[src*="hero.js"'));
+
+        expect(scriptTags.length).to.equal(1);
+        expect(scriptTags[0].getAttribute('type')).to.equal('module-shim');
+        done();
+      });
+    });
+  });
+
+  after(function() {
+    runner.stopCommand();
+    runner.teardown([
+      path.join(outputPath, '.greenwood'),
+      path.join(outputPath, 'node_modules')
+    ]);
+  });
+});
\ No newline at end of file
diff --git a/packages/cli/test/cases/develop.config.polyfills-import-maps/greenwood.config.js b/packages/cli/test/cases/develop.config.polyfills-import-maps/greenwood.config.js
new file mode 100644
index 000000000..e6c692170
--- /dev/null
+++ b/packages/cli/test/cases/develop.config.polyfills-import-maps/greenwood.config.js
@@ -0,0 +1,5 @@
+export default {
+  polyfills: {
+    importMaps: true
+  }
+};
\ No newline at end of file
diff --git a/packages/cli/test/cases/develop.config.polyfills-import-maps/package.json b/packages/cli/test/cases/develop.config.polyfills-import-maps/package.json
new file mode 100644
index 000000000..6e4d02164
--- /dev/null
+++ b/packages/cli/test/cases/develop.config.polyfills-import-maps/package.json
@@ -0,0 +1,4 @@
+{
+  "name": "test-develop-command-config-import-maps",
+  "type": "module"
+}
\ No newline at end of file
diff --git a/packages/cli/test/cases/develop.config.polyfills-import-maps/src/components/hero.js b/packages/cli/test/cases/develop.config.polyfills-import-maps/src/components/hero.js
new file mode 100644
index 000000000..b9ec664dc
--- /dev/null
+++ b/packages/cli/test/cases/develop.config.polyfills-import-maps/src/components/hero.js
@@ -0,0 +1,64 @@
+const template = document.createElement('template');
+
+template.innerHTML = `
+  <style>
+    :host {
+    text-align: center;
+    margin-bottom: 40px;
+  }
+
+  :host h2 {
+    font-size: 3em;
+  }
+
+  :host button {
+    display: inline-block;
+    background-color: var(--color-primary);
+    color: var(--color-white);
+    font-size: 1.5em;
+    padding: 14px;
+    border-radius: 10px;
+    cursor: pointer;
+  }
+  </style>
+  <div class="hero">
+    <h2>Welcome to my website</h2>
+    
+    <a href="#">
+      <button>Get Started</button>
+    </a>
+    <a href="#">
+      <button>Learn More &#8594</button>
+    </a>
+
+  </div>
+`;
+
+export default class HeroBanner extends HTMLElement {
+  clickButton(el) {
+    const content = el.textContent;
+    const buttonClickedEvent = new CustomEvent('update-modal', {
+      detail: {
+        content: `You selected "${content}"`
+      }
+    });
+
+    console.log('clicked button =>', content);
+
+    window.dispatchEvent(buttonClickedEvent);
+  }
+
+  connectedCallback() {
+    if (!this.shadowRoot) {
+      this.attachShadow({ mode: 'open' });
+      this.shadowRoot.appendChild(template.content.cloneNode(true));
+    }
+
+    this.shadowRoot.querySelectorAll('button')
+      .forEach(button => {
+        button.addEventListener('click', () => this.clickButton(button));
+      });
+  }
+}
+
+customElements.define('app-hero', HeroBanner);
\ No newline at end of file
diff --git a/packages/cli/test/cases/develop.config.polyfills-import-maps/src/index.html b/packages/cli/test/cases/develop.config.polyfills-import-maps/src/index.html
new file mode 100644
index 000000000..87e929b43
--- /dev/null
+++ b/packages/cli/test/cases/develop.config.polyfills-import-maps/src/index.html
@@ -0,0 +1,11 @@
+<html>
+
+  <head>
+    <script type="module" src="./components/hero.js"></script>
+  </head>
+
+  <body>
+    <app-hero></app-hero>
+  </body>
+  
+</html>
\ No newline at end of file
diff --git a/packages/cli/test/cases/develop.default/develop.default.spec.js b/packages/cli/test/cases/develop.default/develop.default.spec.js
index 610243c55..3d236e7ea 100644
--- a/packages/cli/test/cases/develop.default/develop.default.spec.js
+++ b/packages/cli/test/cases/develop.default/develop.default.spec.js
@@ -488,7 +488,7 @@ describe('Develop Greenwood With: ', function() {
       });
 
       it('should return an import map shim <script> in the <head> of the document', function(done) {
-        const importMapTag = dom.window.document.querySelectorAll('head > script[type="importmap-shim"]')[0];
+        const importMapTag = dom.window.document.querySelectorAll('head > script[type="importmap"]')[0];
         const importMap = JSON.parse(importMapTag.textContent).imports;
 
         Object.keys(expectedImportMap).forEach((key) => {
@@ -524,15 +524,6 @@ describe('Develop Greenwood With: ', function() {
         done();
       });
 
-      it('should return an import map in the <head> of the document', function(done) {
-        const importMapShimTag = dom.window.document.querySelectorAll('head > script[defer]')[0];
-        const shimSrc = importMapShimTag.getAttribute('src');
-
-        expect(shimSrc).to.equal('/node_modules/es-module-shims/dist/es-module-shims.js');
-
-        done();
-      });
-
       it('should add a <script> tag for livereload', function(done) {
         const scriptTags = Array.from(dom.window.document.querySelectorAll('head > script[src]'));
         const livereloadScript = scriptTags.filter((tag) => {
diff --git a/packages/cli/test/cases/loaders-serve.config.polyfill-import-attributes/greenwood.config.js b/packages/cli/test/cases/loaders-serve.config.polyfill-import-attributes/greenwood.config.js
new file mode 100644
index 000000000..8c604b978
--- /dev/null
+++ b/packages/cli/test/cases/loaders-serve.config.polyfill-import-attributes/greenwood.config.js
@@ -0,0 +1,6 @@
+export default {
+  prerender: true,
+  polyfills: {
+    importAttributes: ['css', 'json']
+  }
+};
\ No newline at end of file
diff --git a/packages/cli/test/cases/loaders-serve.config.polyfill-import-attributes/loaders-serve.config.polyfills-import-attributes.spec.js b/packages/cli/test/cases/loaders-serve.config.polyfill-import-attributes/loaders-serve.config.polyfills-import-attributes.spec.js
new file mode 100644
index 000000000..26ee1ae51
--- /dev/null
+++ b/packages/cli/test/cases/loaders-serve.config.polyfill-import-attributes/loaders-serve.config.polyfills-import-attributes.spec.js
@@ -0,0 +1,178 @@
+/*
+ * Use Case
+ * Run Greenwood serve command with import attributes polyfill flag enabled.
+ *
+ * User Result
+ * Should start the production server and have all the expected import attributes polyfill behaviors..
+ *
+ * User Command
+ * greenwood serve
+ *
+ * User Config
+ * {
+ *   prerender: true,
+ *   polyfill: {
+ *     importAttributes: ['css', 'json']
+ *   }
+ * }
+ *
+ * User Workspace
+ * src/
+ *   components/
+ *     hero.js
+ *     hero.css
+ *     hero.json
+ *   index.html
+ *   theme.css
+ * greenwood.config.js
+ * package.json
+ *
+ */
+import chai from 'chai';
+import fs from 'fs';
+import { JSDOM } from 'jsdom';
+import path from 'path';
+import { getSetupFiles, getOutputTeardownFiles, getDependencyFiles } from '../../../../../test/utils.js';
+import { Runner } from 'gallinago';
+import { fileURLToPath, URL } from 'url';
+
+const expect = chai.expect;
+
+describe('Serve Greenwood With: ', function() {
+  const LABEL = 'Import Attributes Polyfill Configuration and prerendering';
+  const cliPath = path.join(process.cwd(), 'packages/cli/src/index.js');
+  const outputUrl = new URL('.', import.meta.url);
+  const outputPath = fileURLToPath(outputUrl);
+  const hostname = 'http://127.0.0.1:8080';
+  let runner;
+
+  before(function() {
+    this.context = {
+      hostname
+    };
+    runner = new Runner(false, true);
+  });
+
+  describe(LABEL, function() {
+
+    before(async function() {
+      const greenwoodRouterLibs = await getDependencyFiles(
+        `${process.cwd()}/packages/cli/src/lib/router.js`,
+        `${outputPath}/node_modules/@greenwood/cli/src/lib`
+      );
+
+      runner.setup(outputPath, [
+        ...getSetupFiles(outputPath),
+        ...greenwoodRouterLibs
+      ]);
+      runner.runCommand(cliPath, 'build');
+
+      return new Promise((resolve) => {
+        setTimeout(() => {
+          resolve();
+        }, 10000);
+
+        runner.runCommand(cliPath, 'serve', { async: true });
+      });
+    });
+
+    describe('Import Attributes Polyfill Behaviors when used for pre-rendering and returning HTML', function() {
+      let response;
+      let dom;
+
+      before(async function() {
+        response = await fetch(`${hostname}/`);
+        dom = new JSDOM(await response.text());
+      });
+
+      it('should return the correct content type', function(done) {
+        expect(response.headers.get('content-type')).to.contain('text/html');
+        done();
+      });
+
+      it('should return a 200', function(done) {
+        expect(response.status).to.equal(200);
+
+        done();
+      });
+
+      it('should have the expected SSR output in the HTML for an <h2> tag from JSON import', function(done) {
+        const hero = new JSDOM(dom.window.document.querySelectorAll('app-hero template[shadowrootmode="open"]')[0].innerHTML);
+        const headings = hero.window.document.querySelectorAll('div h2');
+
+        expect(headings.length).to.equal(1);
+        expect(headings[0].textContent).to.equal('Hello World');
+
+        done();
+      });
+
+      it('should have the expected SSR output in the HTML for <a> tags', function(done) {
+        const hero = new JSDOM(dom.window.document.querySelectorAll('app-hero template[shadowrootmode="open"]')[0].innerHTML);
+        const links = hero.window.document.querySelectorAll('div a');
+
+        expect(links.length).to.equal(2);
+        expect(links[0].getAttribute('href')).to.equal('/get-started');
+        expect(links[1].getAttribute('href')).to.equal('/learn-more');
+
+        done();
+      });
+    });
+
+    describe('Import Attributes Polyfill Behaviors for the initiating JavaScript file (hero.js) being served and bundled', function() {
+      const jsHash = '9acf7b4c';
+      let response = {};
+      let text;
+      let contents;
+
+      before(async function() {
+        response = await fetch(`${hostname}/hero.${jsHash}.js`);
+        text = await response.clone().text();
+        contents = await fs.promises.readFile(new URL(`./public/hero.${jsHash}.js`, outputUrl), 'utf-8');
+      });
+
+      it('should return the correct content type', function(done) {
+        expect(response.headers.get('content-type')).to.contain('text/javascript');
+        done();
+      });
+
+      it('should return a 200', function(done) {
+        expect(response.status).to.equal(200);
+
+        done();
+      });
+
+      it('should not contain import attributes syntax in the response or bundled output', function(done) {
+        expect(text.replace(/ /g, '')).to.not.contain('with{type:');
+        expect(contents.replace(/ /g, '')).to.not.contain('with{type:');
+
+        done();
+      });
+
+      it('should contain import attributes polyfill syntax for the theme CSS', function(done) {
+        expect(text).to.contain('const t=new CSSStyleSheet;t.replaceSync("a{color:blue}");');
+        expect(contents).to.contain('const t=new CSSStyleSheet;t.replaceSync("a{color:blue}");');
+
+        done();
+      });
+
+      it('should contain import attributes polyfill syntax for the component CSS', function(done) {
+        expect(text).to.contain('const e=new CSSStyleSheet;e.replaceSync(":host h2{font-size:3em}");');
+        expect(contents).to.contain('const e=new CSSStyleSheet;e.replaceSync(":host h2{font-size:3em}");');
+
+        done();
+      });
+
+      it('should contain import attributes polyfill syntax for JSON', function(done) {
+        expect(text).to.contain('var n="Hello World";');
+        expect(contents).to.contain('var n="Hello World";');
+
+        done();
+      });
+    });
+  });
+
+  after(function() {
+    runner.teardown(getOutputTeardownFiles(outputPath));
+    runner.stopCommand();
+  });
+});
\ No newline at end of file
diff --git a/packages/cli/test/cases/loaders-serve.config.polyfill-import-attributes/src/components/hero.css b/packages/cli/test/cases/loaders-serve.config.polyfill-import-attributes/src/components/hero.css
new file mode 100644
index 000000000..cbc4a27e7
--- /dev/null
+++ b/packages/cli/test/cases/loaders-serve.config.polyfill-import-attributes/src/components/hero.css
@@ -0,0 +1,3 @@
+:host h2 {
+  font-size: 3em;
+}
\ No newline at end of file
diff --git a/packages/cli/test/cases/loaders-serve.config.polyfill-import-attributes/src/components/hero.js b/packages/cli/test/cases/loaders-serve.config.polyfill-import-attributes/src/components/hero.js
new file mode 100644
index 000000000..e350e6831
--- /dev/null
+++ b/packages/cli/test/cases/loaders-serve.config.polyfill-import-attributes/src/components/hero.js
@@ -0,0 +1,33 @@
+// intentionally break formatting to validate our AST parsing is not impacted / naive
+import sheet from './hero.css' with { type: 'css' };
+import theme from '../theme.css' with { type: 'css' };
+import data from './hero.json' with { type: 'json' };
+
+const template = document.createElement('template');
+
+export default class HeroBanner extends HTMLElement {
+  connectedCallback() {
+    if (!this.shadowRoot) {
+      template.innerHTML = `
+        <div class="hero">
+          <h2>${data.msg}</h2>
+          
+          <a href="/get-started">
+            <button>Get Started</button>
+          </a>
+          <a href="/learn-more">
+            <button>Learn More &#8594</button>
+          </a>
+
+        </div>
+      `;
+
+      this.attachShadow({ mode: 'open' });
+      this.shadowRoot.appendChild(template.content.cloneNode(true));
+    }
+
+    this.shadowRoot.adoptedStyleSheets = [theme, sheet];
+  }
+}
+
+customElements.define('app-hero', HeroBanner);
\ No newline at end of file
diff --git a/packages/cli/test/cases/loaders-serve.config.polyfill-import-attributes/src/components/hero.json b/packages/cli/test/cases/loaders-serve.config.polyfill-import-attributes/src/components/hero.json
new file mode 100644
index 000000000..45437a894
--- /dev/null
+++ b/packages/cli/test/cases/loaders-serve.config.polyfill-import-attributes/src/components/hero.json
@@ -0,0 +1,3 @@
+{
+  "msg": "Hello World"
+}
\ No newline at end of file
diff --git a/packages/cli/test/cases/loaders-serve.config.polyfill-import-attributes/src/index.html b/packages/cli/test/cases/loaders-serve.config.polyfill-import-attributes/src/index.html
new file mode 100644
index 000000000..87e929b43
--- /dev/null
+++ b/packages/cli/test/cases/loaders-serve.config.polyfill-import-attributes/src/index.html
@@ -0,0 +1,11 @@
+<html>
+
+  <head>
+    <script type="module" src="./components/hero.js"></script>
+  </head>
+
+  <body>
+    <app-hero></app-hero>
+  </body>
+  
+</html>
\ No newline at end of file
diff --git a/packages/cli/test/cases/loaders-serve.config.polyfill-import-attributes/src/theme.css b/packages/cli/test/cases/loaders-serve.config.polyfill-import-attributes/src/theme.css
new file mode 100644
index 000000000..0f7c63922
--- /dev/null
+++ b/packages/cli/test/cases/loaders-serve.config.polyfill-import-attributes/src/theme.css
@@ -0,0 +1,3 @@
+a {
+  color: blue;
+}
\ No newline at end of file
diff --git a/packages/plugin-graphql/test/cases/develop.default/develop.default.spec.js b/packages/plugin-graphql/test/cases/develop.default/develop.default.spec.js
index ef0daa1c3..07a6d4f2b 100644
--- a/packages/plugin-graphql/test/cases/develop.default/develop.default.spec.js
+++ b/packages/plugin-graphql/test/cases/develop.default/develop.default.spec.js
@@ -77,7 +77,7 @@ describe('Develop Greenwood With: ', function() {
       });
 
       it('should return an import map shim <script> in the <head> of the document', function(done) {
-        const importMapTag = dom.window.document.querySelectorAll('head > script[type="importmap-shim"]')[0];
+        const importMapTag = dom.window.document.querySelectorAll('head > script[type="importmap"]')[0];
         const importMap = JSON.parse(importMapTag.textContent).imports;
 
         expect(importMap['@greenwood/plugin-graphql/src/core/client.js']).to.equal('/node_modules/@greenwood/plugin-graphql/src/core/client.js');
diff --git a/packages/plugin-import-raw/src/index.js b/packages/plugin-import-raw/src/index.js
index 499b7e382..e9a2a58e7 100644
--- a/packages/plugin-import-raw/src/index.js
+++ b/packages/plugin-import-raw/src/index.js
@@ -36,12 +36,11 @@ class ImportRawResource extends ResourceInterface {
     return new Request(matchedUrl);
   }
 
-  async shouldIntercept(url, request) {
+  async shouldIntercept(url) {
     const matches = (this.options.matches || []).filter(matcher => url.href.indexOf(matcher) >= 0);
     const type = url.searchParams.get('type');
-    const dest = request.headers.get('Sec-Fetch-Dest');
 
-    return (url.protocol === 'file:' && type === 'raw' && dest === 'empty') || matches.length > 0;
+    return (url.protocol === 'file:' && type === 'raw') || matches.length > 0;
   }
 
   async intercept(url, request, response) {
diff --git a/packages/plugin-import-raw/test/cases/develop.default/develop.default.spec.js b/packages/plugin-import-raw/test/cases/develop.default/develop.default.spec.js
index 98570b3cd..187eef0c7 100644
--- a/packages/plugin-import-raw/test/cases/develop.default/develop.default.spec.js
+++ b/packages/plugin-import-raw/test/cases/develop.default/develop.default.spec.js
@@ -67,11 +67,7 @@ describe('Develop Greenwood With: ', function() {
       let data;
 
       before(async function() {
-        response = await fetch(`${hostname}:${port}/main.css?type=raw`, {
-          headers: {
-            'Sec-Fetch-Dest': 'empty'
-          }
-        });
+        response = await fetch(`${hostname}:${port}/main.css?type=raw`);
         data = await response.text();
       });
 
diff --git a/packages/plugin-renderer-lit/src/index.js b/packages/plugin-renderer-lit/src/index.js
index 4f33502bd..ca77f421c 100755
--- a/packages/plugin-renderer-lit/src/index.js
+++ b/packages/plugin-renderer-lit/src/index.js
@@ -13,18 +13,16 @@ class LitHydrationResource extends ResourceInterface {
   }
 
   async intercept(url, request, response) {
-    let body = await response.text();
-
-    // TODO would be nice not have to manually set module-shim
-    // when we drop support for import-map shim - https://github.com/ProjectEvergreen/greenwood/pull/1115
-    const type = process.env.__GWD_COMMAND__ === 'develop' // eslint-disable-line  no-underscore-dangle
+    const { importMaps } = this.compilation.config.polyfills;
+    const importMapType = process.env.__GWD_COMMAND__ === 'develop' && importMaps // eslint-disable-line  no-underscore-dangle
       ? 'module-shim'
       : 'module';
+    let body = await response.text();
 
     // this needs to come first before any userland code
     body = body.replace('<head>', `
       <head>
-        <script type="${type}" src="/node_modules/@lit-labs/ssr-client/lit-element-hydrate-support.js"></script>
+        <script type="${importMapType}" src="/node_modules/@lit-labs/ssr-client/lit-element-hydrate-support.js"></script>
     `);
 
     return new Response(body);
diff --git a/www/pages/docs/configuration.md b/www/pages/docs/configuration.md
index 37cc894a6..6779cc57d 100644
--- a/www/pages/docs/configuration.md
+++ b/www/pages/docs/configuration.md
@@ -32,7 +32,11 @@ export default {
   workspace: new URL('./src/', import.meta.url),
   pagesDirectory: 'pages', // e.g. src/pages
   layoutsDirectory: 'layouts', // e.g. src/layouts
-  isolation: false
+  isolation: false,
+  polyfills: {
+    importAttributes: null, // e.g. ['css', 'json']
+    importMaps: false
+  }
 };
 ```
 
@@ -220,6 +224,57 @@ export default {
 };
 ```
 
+### Polyfills
+
+Greenwood provides polyfills for a few Web APIs out of the box.
+
+#### Import Maps
+
+> _Only applies to development mode._
+
+If you are developing with Greenwood in a browser that doesn't support [import maps](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap#browser_compatibility), with this flag enabled, Greenwood will add the [**ES Module Shims**](https://github.com/guybedford/es-module-shims) polyfill to provide support for import maps.
+
+```js
+export default {
+  polyfills: {
+    importMaps: true
+  }
+};
+```
+
+#### Import Attributes
+
+[Import Attributes](https://github.com/tc39/proposal-import-attributes), which are the underlying mechanism for supporting [CSS](https://web.dev/articles/css-module-scripts) and [JSON](https://github.com/tc39/proposal-json-modules) module scripts, are not widely supported in [all browsers yet](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules#browser_compatibility).  Greenwood can enable this in a browser compatible why by specifying which attributes you want handled.  In both cases, Greenwood bundles these as ES Modules and will strip the attributes syntax.
+
+```js
+export default {
+  polyfills: {
+    importAttributes: ['css', 'json']
+  }
+};
+```
+
+
+In the case of CSS, Greenwood will inline and export your CSS as a [Constructable Stylesheet](https://web.dev/articles/constructable-stylesheets)
+
+```js
+// this
+import sheet from './styles.css' with { type: 'css'};
+
+// will fallback to this
+const sheet = new CSSStyleSheet();sheet.replaceSync(' /* ... */ ');export default sheet;
+```
+
+For JSON, Greenwood will simply export an object
+
+```js
+// this
+import data from './data.css' with { type: 'json'};
+
+// will fallback to this
+export default { /* ... */ }
+```
+
 ### Port
 Unlike the port option for `devServer` configuration, this option allows you to configure the port that your production server will run on when running `greenwood serve`.
 
diff --git a/www/pages/docs/css-and-images.md b/www/pages/docs/css-and-images.md
index c15502540..2b450e4fb 100644
--- a/www/pages/docs/css-and-images.md
+++ b/www/pages/docs/css-and-images.md
@@ -75,6 +75,8 @@ export default class Card extends HTMLElement {
 customElements.define('x-card', Card);
 ```
 
+> ⚠️ _Although Import Attributes are not baseline yet, Greenwood supports polyfilling them with a [configuration flag](/docs/configuration/#polyfills)._
+
 
 ### Assets
 
diff --git a/www/pages/docs/scripts.md b/www/pages/docs/scripts.md
index 4bee33f9d..3c94461e5 100644
--- a/www/pages/docs/scripts.md
+++ b/www/pages/docs/scripts.md
@@ -55,16 +55,14 @@ Greenwood also supports (and recommends) usage of ECMAScript Modules (ESM), like
 
 ### Import Attributes
 
-[Import Attributes](https://github.com/tc39/proposal-import-attributes) are also supported on the client and on [the server](docs/server-rendering/#custom-imports).  By default automatically handles CSS and JSON modules and for CSS, emits a [`CSSStylesheet`](https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleSheet/CSSStyleSheet).
+Greenwood supports [Import Attributes](https://github.com/tc39/proposal-import-attributes) for the client and the [the server](docs/server-rendering/#custom-imports) seamlessly, supporting both CSS and JSON module scripts seamlessly.
 
 ```js
 import sheet from './styles.css' with { type: 'css' };
 import data from './data.json' with { type: 'json' };
-
-console.log({ sheet, data });
 ```
 
-Combined with Greenwood's [custom import resource plugins](https://www.greenwoodjs.io/plugins/custom-plugins/) (or your own!), Greenwood can handle loading custom file extensions for the client or the server using ESM for just about anything you could need!
+> ⚠️ _Although Import Attributes are not baseline yet, Greenwood supports polyfilling them with a [configuration flag](/docs/configuration/#polyfills)._
 
 ### Extensions and Bare Imports