Add ESM bundle support (#1280)

* add ESM support

* address copilot feedback

* fix icons

* fix linter

* fix octicons externals

* fix typing erroprs

* fix cjs path for astro

* upgrade astro to v6 and switch to ESM

* update astro to support matrix strategy for cjs and esm

* add stylesheets file to side effects

* upgrade to vite 8

* update package-lock

* fix build

* update vite config

* pin postcss

* fix side-effects path

Author: rezrah

.changeset/free-planets-fold.md

@@ -0,0 +1,19 @@
+---
+'@primer/react-brand': minor
+---
+
+Added ESM library support.
+
+A new `@primer/react-brand/esm` entry point is now available for modern bundlers (E.g. Vite, Next.js, etc).
+
+Components imported from this path automatically include the minimum CSS needed. Separate global stylesheet imports are no longer required.
+
+```js
+import {Hero, ThemeProvider} from '@primer/react-brand/esm'
+```
+
+ESM features are opt-in, and the previous UMD bundle (`@primer/react-brand`) and global CSS (`@primer/react-brand/lib/css/main.css`) continue to work as before.
+
+We recommend switching to ESM as soon as possible, as it will eventually become the default in future.
+
+🔗 [Get started with ESM](https://primer.style/brand/getting-started/esm)

.github/workflows/bundle_size.yml

@@ -0,0 +1,65 @@
+name: Check bundle size
+
+on:
+  pull_request:
+
+jobs:
+  size:
+    if: ${{ github.repository == 'primer/brand' }}
+    name: Report bundle size
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout PR branch
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Create main branch worktree
+        run: git worktree add /tmp/main ${{ github.event.pull_request.base.sha }}
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+
+      - name: Caching dependencies
+        uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-node-
+
+      - name: Install and build (PR)
+        run: |
+          npm ci
+          npm run build:lib
+
+      - name: Measure bundle size (PR)
+        run: npx size-limit --json > /tmp/pr-sizes.json
+
+      - name: Install and build (main branch)
+        working-directory: /tmp/main
+        run: |
+          npm ci
+          cp ${{ github.workspace }}/.size-limit.js .size-limit.js
+          npm run build:lib
+
+      - name: Measure bundle size (main branch)
+        working-directory: /tmp/main
+        run: npx size-limit --json > /tmp/main-sizes.json 2>/dev/null || echo "[]" > /tmp/main-sizes.json
+
+      - name: Generate size report
+        id: size-report
+        run: |
+          REPORT=$(node packages/repo-configs/scripts/bundle-size-report.js /tmp/pr-sizes.json /tmp/main-sizes.json)
+          echo "comment-body<<EOF" >> "$GITHUB_OUTPUT"
+          echo "$REPORT" >> "$GITHUB_OUTPUT"
+          echo "EOF" >> "$GITHUB_OUTPUT"
+
+      - name: Add or update bundle size comment
+        uses: phulsechinmay/rewritable-pr-comment@v0.3.0
+        with:
+          message: ${{ steps.size-report.outputs.comment-body }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          COMMENT_IDENTIFIER: 'bundle-size-report'

.github/workflows/integration_test_astro.yml

@@ -8,15 +8,23 @@ on:
     - cron: '0 0 * * *' # end of each day (UTC)
   pull_request:
 
-env:
-  ASTRO_FOLDER: astro-test
-
 jobs:
   test:
     if: ${{ github.repository == 'primer/brand' }}
-    name: Astro - React starter
+    name: Astro (${{ matrix.bundle }})
     runs-on:
       labels: ubuntu-latest-16-cores
+    strategy:
+      fail-fast: false
+      matrix:
+        bundle: [umd, esm]
+        include:
+          - bundle: umd
+            astro_folder: astro-test
+          - bundle: esm
+            astro_folder: astro-esm-test
+    env:
+      ASTRO_FOLDER: ${{ matrix.astro_folder }}
     steps:
       - name: Checkout repository
         uses: actions/checkout@v6
@@ -88,13 +96,14 @@ jobs:
           cp ../packages/react/primer-react-brand-${{ steps.package-version.outputs.current-version}}.tgz ./
           npm install primer-react-brand-${{ steps.package-version.outputs.current-version}}.tgz
 
-      - name: Prefer CommonJS imports
+      - name: Prepare barrel file for bundle type
         run: |
-          mv packages/e2e/integration-tests/fixtures/index.cjs.ts packages/e2e/integration-tests/fixtures/index.ts
-          rm packages/e2e/integration-tests/fixtures/index.esm.ts
+          cp ./packages/e2e/integration-tests/fixtures/index.${{ matrix.bundle }}.ts ./packages/e2e/integration-tests/fixtures/index.ts
+          rm ./packages/e2e/integration-tests/fixtures/index.umd.ts ./packages/e2e/integration-tests/fixtures/index.esm.ts
 
       - name: Copying required files
         run: |
+          cp packages/e2e/integration-tests/astro/astro.config.mjs ./${{env.ASTRO_FOLDER}}/astro.config.mjs
           cp packages/e2e/integration-tests/astro/index.astro ./${{env.ASTRO_FOLDER}}/src/pages
           cp packages/e2e/cypress.config.js ./${{env.ASTRO_FOLDER}}/cypress.config.cjs
           cp -r packages/e2e/integration-tests/fixtures ./${{env.ASTRO_FOLDER}}/src

.github/workflows/integration_test_nextjs.yml

@@ -1,4 +1,4 @@
-name: Integration test
+name: Integration test (Next.js)
 
 on:
   push:
@@ -8,15 +8,23 @@ on:
     - cron: '0 0 * * *' # end of each day (UTC)
   pull_request:
 
-env:
-  NEXTJS_FOLDER: next-js-test
-
 jobs:
   test:
     if: ${{ github.repository == 'primer/brand' }}
-    name: Next.js
+    name: Next.js (${{ matrix.bundle }})
     runs-on:
       labels: ubuntu-latest-16-cores
+    strategy:
+      fail-fast: false
+      matrix:
+        bundle: [umd, esm]
+        include:
+          - bundle: umd
+            nextjs_folder: next-js-test
+          - bundle: esm
+            nextjs_folder: next-js-esm-test
+    env:
+      NEXTJS_FOLDER: ${{ matrix.nextjs_folder }}
     steps:
       - name: Checkout repository
         uses: actions/checkout@v6
@@ -34,10 +42,6 @@ jobs:
           restore-keys: |
             ${{ runner.os }}-node-
 
-      # Restore the previous NPM modules and Cypress binary archives.
-      # Any updated archives will be saved automatically after the entire
-      # workflow successfully finishes.
-      # See https://github.com/actions/cache
       - name: Cache Cypress binary
         uses: actions/cache@v5
         with:
@@ -51,9 +55,7 @@ jobs:
 
       - name: install dependencies and verify Cypress
         env:
-          # make sure every Cypress install prints minimal information
           CI: 1
-        # print Cypress and OS info
         run: |
           npx cypress@15.13.0 install --force
           npx cypress@15.13.0 verify
@@ -81,45 +83,40 @@ jobs:
 
       - name: Installing local build
         run: |
-          cd ${{env.NEXTJS_FOLDER}}
-          cp ../packages/react/primer-react-brand-${{ steps.package-version.outputs.current-version}}.tgz ./
-          npm install primer-react-brand-${{ steps.package-version.outputs.current-version}}.tgz
+          cd ${{ env.NEXTJS_FOLDER }}
+          cp ../packages/react/primer-react-brand-${{ steps.package-version.outputs.current-version }}.tgz ./
+          npm install primer-react-brand-${{ steps.package-version.outputs.current-version }}.tgz
 
-      - name: Prefer ESM imports
+      - name: Prepare barrel file for bundle type
         run: |
-          mv ./packages/e2e/integration-tests/fixtures/index.esm.ts ./packages/e2e/integration-tests/fixtures/index.ts
-          rm ./packages/e2e/integration-tests/fixtures/index.cjs.ts
+          cp ./packages/e2e/integration-tests/fixtures/index.${{ matrix.bundle }}.ts ./packages/e2e/integration-tests/fixtures/index.ts
+          rm ./packages/e2e/integration-tests/fixtures/index.umd.ts ./packages/e2e/integration-tests/fixtures/index.esm.ts
 
       - name: Copying required files
         run: |
-          rm ./${{env.NEXTJS_FOLDER}}/app/page.tsx
-          cp ./packages/e2e/integration-tests/nextjs/page.tsx ./${{env.NEXTJS_FOLDER}}/app
-
-      - name: Copying required files
-        run: |
-          cp ./packages/e2e/integration-tests/nextjs/page.tsx ./${{env.NEXTJS_FOLDER}}/app
-          cp ./packages/e2e/cypress.config.js ./${{env.NEXTJS_FOLDER}}
-          mkdir ${{env.NEXTJS_FOLDER}}/integration-tests
-          cp -r ./packages/e2e/integration-tests/fixtures ./${{env.NEXTJS_FOLDER}}/integration-tests
-          cp -r ./packages/e2e/integration-tests/tests ./${{env.NEXTJS_FOLDER}}/integration-tests
+          rm ./${{ env.NEXTJS_FOLDER }}/app/page.tsx
+          cp ./packages/e2e/integration-tests/nextjs/page.tsx ./${{ env.NEXTJS_FOLDER }}/app
+          cp ./packages/e2e/cypress.config.js ./${{ env.NEXTJS_FOLDER }}
+          mkdir ${{ env.NEXTJS_FOLDER }}/integration-tests
+          cp -r ./packages/e2e/integration-tests/fixtures ./${{ env.NEXTJS_FOLDER }}/integration-tests
+          cp -r ./packages/e2e/integration-tests/tests ./${{ env.NEXTJS_FOLDER }}/integration-tests
 
       - name: Excluded cypress tests in-place
         # includes temp workaround for cypress bug. remove when fixed
         # https://github.com/cypress-io/cypress/issues/27448
         run: npx json@11.0.0 -I -f ${{env.NEXTJS_FOLDER}}/tsconfig.json -e 'this.exclude=["node_modules", "**/*.cy.ts"]; this.compilerOptions.moduleResolution="node"'
 
       - name: Fix monorepo-related linting issues
-        run: |
-          npm run lint -- --fix
+        run: npm run lint -- --fix
 
       # Needed to fix compilation errors and conflicts between TS and React type defs.
       # All subsequent steps should not be dependent on the primer/brand repo contents.
       - name: Clean workspace before testing
         run: |
-          find . -maxdepth 1 -mindepth 1 -not -name ${{env.NEXTJS_FOLDER}} -exec rm -rf {} +
+          find . -maxdepth 1 -mindepth 1 -not -name ${{ env.NEXTJS_FOLDER }} -exec rm -rf {} +
 
       - name: Testing compile-time build
-        run: cd ${{env.NEXTJS_FOLDER}} && npm run build
+        run: cd ${{ env.NEXTJS_FOLDER }} && npm run build
 
       - name: Test runtime for errors and warnings
         run: cd ${{env.NEXTJS_FOLDER}} && npx start-server-and-test@3.0.0 'start' 3000 'npx cypress@15.13.0 run --spec "./integration-tests/tests/*" --config video=false'

.github/workflows/integration_test_remix.yml

@@ -63,7 +63,7 @@ jobs:
       - name: Prefer ESM imports
         run: |
           mv ./packages/e2e/integration-tests/fixtures/index.esm.ts ./packages/e2e/integration-tests/fixtures/index.ts
-          rm ./packages/e2e/integration-tests/fixtures/index.cjs.ts
+          rm ./packages/e2e/integration-tests/fixtures/index.umd.ts
 
       - name: Copying required files
         run: |

.gitignore

@@ -3,6 +3,7 @@ node_modules
 
 #output
 lib/
+esm/
 storybook-static
 
 # testing
@@ -36,4 +37,5 @@ debug-storybook.log
 next-js-test/
 cra-test/
 astro-test/
-remix-test/
+remix-test/
+esm-test/

.size-limit.js

@@ -0,0 +1,32 @@
+module.exports = [
+  {
+    name: 'UMD — full bundle (JS)',
+    path: 'packages/react/lib/index.js',
+  },
+  {
+    name: 'UMD — full bundle (CSS)',
+    path: 'packages/react/lib/css/main.css',
+  },
+  {
+    name: 'ESM — full bundle (JS + CSS)',
+    path: 'packages/react/esm/**/*.{js,css}',
+  },
+  {
+    name: 'ESM — tree-shaken simple (Button)',
+    path: 'packages/react/esm/index.esm.js',
+    import: '{ Button }',
+    modifyEsbuildConfig(config) {
+      config.external = ['react', 'react-dom']
+      return config
+    },
+  },
+  {
+    name: 'ESM — tree-shaken complex (ActionMenu)',
+    path: 'packages/react/esm/index.esm.js',
+    import: '{ ActionMenu }',
+    modifyEsbuildConfig(config) {
+      config.external = ['react', 'react-dom']
+      return config
+    },
+  },
+]

apps/next-docs/content/getting-started/esm.mdx

@@ -0,0 +1,56 @@
+---
+title: Getting started
+description: Primer Brand is open-sourced on GitHub and available on npm.
+menu-position: 1
+keywords: ['accessibility', 'introduction', 'simple']
+show-tabs: true
+tab-label: ESM
+---
+
+Using ESM, you will load only the React components and CSS you need.
+
+We recommend using ESM if your project uses compatible bundlers or frameworks like Vite or Next.js.
+
+### 1. Install Primer Brand
+
+```shell
+npm install @primer/react-brand
+```
+
+### 2. Import components from the ESM folder
+
+```js
+import {Hero, ThemeProvider} from '@primer/react-brand/esm'
+```
+
+Each component's styles are automatically included when you import the component.
+
+<Note>
+  <p>
+    Do not combine this approach with the global <code>lib/css/main.css</code> import.
+  </p>
+
+  <p>Choose one approach or the other to avoid loading duplicate styles.</p>
+</Note>
+
+### 3. Import the font assets
+
+The Mona Sans typeface still needs to be loaded separately:
+
+```js
+import '@primer/react-brand/fonts/fonts.css'
+```
+
+### 4. Use the `ThemeProvider`
+
+```js
+import {ThemeProvider} from '@primer/react-brand/esm'
+
+function App() {
+  return (
+    <ThemeProvider>
+      <div>...</div>
+    </ThemeProvider>
+  )
+}
+```

…content/introduction/getting-started.mdx …t-docs/content/getting-started/index.mdxapps/next-docs/content/introduction/getting-started.mdx renamed to apps/next-docs/content/getting-started/index.mdx apps/next-docs/content/introduction/getting-started.mdx renamed to apps/next-docs/content/getting-started/index.mdx

@@ -2,7 +2,9 @@
 title: Getting started
 description: Primer Brand is open-sourced on GitHub and available on npm.
 menu-position: 1
-keywords: ['accessibility', 'introduction', 'simple']
+keywords: ['introduction', 'simple', 'get started', 'tutorials']
+show-tabs: true
+tab-label: Default
 ---
 
 Primer Brand is [open-sourced on GitHub](https://github.com/primer/brand) and [available on npm](https://www.npmjs.com/package/@primer/react-brand).
@@ -19,6 +21,11 @@ npm install @primer/react-brand
 
 Primer Brand requires a global stylesheet to be loaded ahead-of-time.
 
+<Note>
+  Refer to [this separate guide if you are using an ESM-compatible bundler](./esm.mdx). Component styles are included
+  with the React component imports.
+</Note>
+
 #### a. Using an application bundler (e.g. Webpack)
 
 Import the `main` stylesheet at the earliest rendering opportunity:

apps/next-docs/content/index.tsx

@@ -43,8 +43,8 @@ export default function HomepageComponent() {
             <Stack padding="none" gap="normal" className={styles.CardGridContainer}>
               <Grid>
                 <Grid.Column span={{xsmall: 12, large: 6, xlarge: 4}}>
-                  <NextLink href="/introduction/getting-started" legacyBehavior passHref>
-                    <Card href="/introduction/getting-started" hasBorder fullWidth>
+                  <NextLink href="/getting-started" legacyBehavior passHref>
+                    <Card href="/getting-started" hasBorder fullWidth>
                       <Card.Heading as="h2">Getting started</Card.Heading>
                       <Card.Description>
                         Standards, guidelines, and tools to get started with Primer Brand.