Add page-tools library (#1271)

silesky · web-flow · commit f2c2b764c168 · 2025-04-09T13:57:49.000-05:00
diff --git a/.buildkite/pipeline.yml b/.buildkite/pipeline.yml
@@ -114,20 +114,24 @@ steps:
           key: "v1.1-cache-dev-{{ checksum 'yarn.lock' }}"
           paths: ['.yarn/cache/']
 
-  - label: '[Generic Utils] Lint + Test'
+  - label: '[Misc Utils] Lint + Test'
     agents:
       queue: v1
     commands:
       - npm config set "//registry.npmjs.org/:_authToken" $${NPM_TOKEN}
       - echo "--- Install dependencies"
       - PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 HUSKY=0 yarn install --immutable
-      - echo "+++ Run QA"
+      - echo "+++ Run QA for generic-utils"
       - yarn turbo run --filter=@segment/analytics-generic-utils lint
       - yarn turbo run --filter=@segment/analytics-generic-utils test
+      - echo "+++ Run QA for page-tools"
+      - yarn turbo run --filter=@segment/analytics-page-tools lint
+      - yarn turbo run --filter=@segment/analytics-page-tools test
     plugins:
       - ssh://git@github.com/segmentio/cache-buildkite-plugin#v2.0.0:
           key: "v1.1-cache-dev-{{ checksum 'yarn.lock' }}"
           paths: ['.yarn/cache/']
+          
 
   - label: '[Consent] Lint + Test'
     agents:
diff --git a/.changeset/bright-readers-wait.md b/.changeset/bright-readers-wait.md
@@ -0,0 +1,5 @@
+---
+'@segment/analytics-next': minor
+---
+
+Refactor to use page-tools package
diff --git a/.changeset/wet-waves-pull.md b/.changeset/wet-waves-pull.md
@@ -0,0 +1,5 @@
+---
+'@segment/analytics-page-tools': major
+---
+
+Release package
diff --git a/package.json b/package.json
@@ -39,6 +39,7 @@
     "@changesets/cli": "^2.23.2",
     "@microsoft/api-extractor": "^7.47.9",
     "@npmcli/promise-spawn": "^7.0.0",
+    "@swc/core": "^1.11.18",
     "@types/express": "4",
     "@types/jest": "^29.5.11",
     "@types/lodash": "^4",
@@ -62,6 +63,7 @@
     "prettier": "^2.6.2",
     "ts-jest": "^29.1.1",
     "ts-node": "^10.8.0",
+    "tsup": "^8.4.0",
     "turbo": "^2.3.4",
     "typescript": "^4.7.0",
     "webpack": "^5.94.0",
diff --git a/packages/browser/.gitignore b/packages/browser/.gitignore
@@ -0,0 +1 @@
+umd.old
diff --git a/packages/browser/package.json b/packages/browser/package.json
@@ -52,6 +52,7 @@
     "@lukeed/uuid": "^2.0.0",
     "@segment/analytics-core": "1.8.1",
     "@segment/analytics-generic-utils": "1.2.0",
+    "@segment/analytics-page-tools": "0.0.1",
     "@segment/analytics.js-video-plugins": "^0.2.1",
     "@segment/facade": "^3.4.9",
     "dset": "^3.1.4",
@@ -79,6 +80,7 @@
     "aws-sdk": "^2.814.0",
     "circular-dependency-plugin": "^5.2.2",
     "compression-webpack-plugin": "^8.0.1",
+    "ecma-version-validator-webpack-plugin": "^1.2.1",
     "execa": "^4.1.0",
     "flat": "^5.0.2",
     "fs-extra": "^9.0.1",
diff --git a/packages/browser/scripts/umd-diff.sh b/packages/browser/scripts/umd-diff.sh
@@ -0,0 +1,35 @@
+#!/bin/bash
+
+# This script is for detecting how the webpack build has changed.
+
+# 1. yarn umd && cp dist/umd dist/umd.old 
+# 2. make changes to your webpack config
+# 3. `bash scripts/umd-diff.sh` to see changes
+
+# Ensure the script stops on errors
+set -e
+
+# Define directories
+DIST_DIR="./dist/umd"
+TMP_DIR="./dist/umd.old"
+
+# Run the UMD build
+echo "Running 'yarn umd' to compile into $DIST_DIR..."
+yarn umd
+
+# Check if the temporary directory exists
+if [ ! -d "$TMP_DIR" ]; then
+  echo "Temporary directory $TMP_DIR does not exist. Exiting."
+  exit 1
+fi
+
+# Compare the directories
+echo "Comparing $DIST_DIR with $TMP_DIR..."
+if command -v colordiff &> /dev/null; then
+  # Use colordiff if available for a prettier diff
+  diff -r "$DIST_DIR" "$TMP_DIR" | grep -E "^(Only in|diff|@@)" | colordiff
+fi
+
+rm 
+# Print completion message
+echo "Comparison complete."
diff --git a/packages/browser/src/core/buffer/index.ts b/packages/browser/src/core/buffer/index.ts
@@ -6,9 +6,9 @@ import { version } from '../../generated/version'
 import { getGlobalAnalytics } from '../../lib/global-analytics-helper'
 import {
   isBufferedPageContext,
-  BufferedPageContext,
   getDefaultBufferedPageContext,
   createPageContext,
+  BufferedPageContext,
   PageContext,
 } from '../page'
 import { getVersionType } from '../../lib/version-type'
diff --git a/packages/browser/src/core/page/add-page-context.ts b/packages/browser/src/core/page/add-page-context.ts
@@ -1,6 +1,6 @@
 import { pick } from '../../lib/pick'
 import { EventProperties, SegmentEvent } from '../events'
-import { getDefaultPageContext } from './get-page-context'
+import { getDefaultPageContext } from '@segment/analytics-page-tools'
 
 /**
  * Augments a segment event with information about the current page.
diff --git a/packages/browser/src/core/page/index.ts b/packages/browser/src/core/page/index.ts
@@ -1,2 +1,12 @@
-export * from './get-page-context'
+export {
+  BufferedPageContextDiscriminant,
+  createBufferedPageContext,
+  createPageContext,
+  getDefaultBufferedPageContext,
+  getDefaultPageContext,
+  isBufferedPageContext,
+  type PageContext,
+  type BufferedPageContext,
+} from '@segment/analytics-page-tools'
+
 export * from './add-page-context'
diff --git a/packages/browser/src/test-helpers/fixtures/page-context.ts b/packages/browser/src/test-helpers/fixtures/page-context.ts
@@ -1,8 +1,8 @@
 import {
-  BufferedPageContext,
+  type BufferedPageContext,
+  type PageContext,
   getDefaultBufferedPageContext,
   getDefaultPageContext,
-  PageContext,
 } from '../../core/page'
 
 export const getPageCtxFixture = (): PageContext => getDefaultPageContext()
diff --git a/packages/browser/webpack.config.js b/packages/browser/webpack.config.js
@@ -1,11 +1,15 @@
+// TODO: use webpack.config.common.js
+
 const path = require('path')
 const webpack = require('webpack')
 const TerserPlugin = require('terser-webpack-plugin')
 const CompressionPlugin = require('compression-webpack-plugin')
 const BundleAnalyzerPlugin =
   require('webpack-bundle-analyzer').BundleAnalyzerPlugin
 const CircularDependencyPlugin = require('circular-dependency-plugin')
-
+const {
+  ECMAVersionValidatorPlugin,
+} = require('ecma-version-validator-webpack-plugin')
 const isProd = process.env.NODE_ENV === 'production'
 
 const ASSET_PATH = process.env.ASSET_PATH
@@ -30,6 +34,10 @@ const plugins = [
   new CircularDependencyPlugin({
     failOnError: true,
   }),
+  // ensure our js bundle only contains syntax supported in ie11.
+  // This does not check polyfills.
+  // This is especially neccessary because by default, node_modules are not transformed.
+  new ECMAVersionValidatorPlugin({ ecmaVersion: 5 }),
 ]
 
 if (process.env.ANALYZE) {
diff --git a/packages/config-tsup/config.js b/packages/config-tsup/config.js
@@ -0,0 +1,19 @@
+const { defineConfig } = require('tsup')
+
+module.exports = defineConfig(() => ({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'], // Output both ESM and CJS formats
+  dts: {
+    resolve: true,
+    entry: 'src/index.ts',
+  },
+  clean: true,
+  esbuildOptions(options, context) {
+    if (context.format === 'esm') {
+      options.outdir = 'dist/esm' // Output ESM files to dist/esm
+      options.outExtension = { '.js': '.mjs' } // Use .mjs for ESM files
+    } else if (context.format === 'cjs') {
+      options.outdir = 'dist/cjs' // Output CJS files to dist/cjs
+    }
+  },
+}))
diff --git a/packages/config-tsup/package.json b/packages/config-tsup/package.json
@@ -0,0 +1,9 @@
+{
+  "name": "@internal/config-tsup",
+  "version": "0.0.0",
+  "private": true,
+  "packageManager": "yarn@3.4.1",
+  "devDependencies": {
+    "tsup": "^8.4.0"
+  }
+}
diff --git a/packages/page-tools/.eslintrc.js b/packages/page-tools/.eslintrc.js
@@ -0,0 +1,4 @@
+/** @type { import('eslint').Linter.Config } */
+module.exports = {
+  extends: ['../../.eslintrc'],
+}
diff --git a/packages/page-tools/.lintstagedrc.js b/packages/page-tools/.lintstagedrc.js
@@ -0,0 +1 @@
+module.exports = require("@internal/config").lintStagedConfig
diff --git a/packages/page-tools/LICENSE b/packages/page-tools/LICENSE
@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright © 2025 Segment
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
diff --git a/packages/page-tools/README.md b/packages/page-tools/README.md
@@ -0,0 +1,3 @@
+# @segment/analytics-page-tools
+
+Browser-only helpers for generating page events with analytics.js. 
diff --git a/packages/page-tools/jest.config.js b/packages/page-tools/jest.config.js
@@ -0,0 +1,5 @@
+const { createJestTSConfig } = require('@internal/config')
+
+module.exports = createJestTSConfig(__dirname, {
+  testEnvironment: 'jsdom',
+})
diff --git a/packages/page-tools/package.json b/packages/page-tools/package.json
@@ -0,0 +1,40 @@
+{
+  "name": "@segment/analytics-page-tools",
+  "version": "0.0.1",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/segmentio/analytics-next",
+    "directory": "packages/page-tools"
+  },
+  "license": "MIT",
+  "module": "./dist/esm/index.mjs",
+  "main": "./dist/cjs/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "files": [
+    "LICENSE",
+    "dist/",
+    "!**/__tests__/**",
+    "!**/test-helpers/**",
+    "!*.tsbuildinfo"
+  ],
+  "scripts": {
+    "build": "yarn tsup --config tsup.config.js",
+    "lint": "yarn concurrently 'yarn:eslint .' 'yarn:tsc --noEmit'",
+    "tsup": "yarn run -T tsup",
+    "test": "yarn jest",
+    "watch": "yarn build:esm --watch",
+    "watch:test": "yarn test --watch",
+    "tsc": "yarn run -T tsc",
+    "eslint": "yarn run -T eslint",
+    "concurrently": "yarn run -T concurrently",
+    "jest": "yarn run -T jest"
+  },
+  "dependencies": {
+    "tslib": "^2.4.1"
+  },
+  "devDependencies": {
+    "@internal/config": "workspace:^",
+    "@internal/config-tsup": "workspace:^"
+  }
+}
diff --git a/packages/page-tools/src/__tests__/page-context.test.ts b/packages/page-tools/src/__tests__/page-context.test.ts
diff --git a/packages/page-tools/src/index.ts b/packages/page-tools/src/index.ts
diff --git a/packages/page-tools/src/page-context.ts b/packages/page-tools/src/page-context.ts
diff --git a/packages/page-tools/tsconfig.build.json b/packages/page-tools/tsconfig.build.json
diff --git a/packages/page-tools/tsconfig.json b/packages/page-tools/tsconfig.json
diff --git a/packages/page-tools/tsup.config.js b/packages/page-tools/tsup.config.js
diff --git a/packages/signals/signals-integration-tests/tsconfig.json b/packages/signals/signals-integration-tests/tsconfig.json
diff --git a/playgrounds/standalone-playground/package.json b/playgrounds/standalone-playground/package.json
diff --git a/yarn.lock b/yarn.lock

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'@segment/analytics-next': minor
 +---
++
 +Refactor to use page-tools package