Add page-tools library

.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://[email protected]/segmentio/cache-buildkite-plugin#v2.0.0:
           key: "v1.1-cache-dev-{{ checksum 'yarn.lock' }}"
           paths: ['.yarn/cache/']
+
 
   - label: '[Consent] Lint + Test'
     agents:

.changeset/bright-readers-wait.md

@@ -0,0 +1,5 @@
+---
+'@segment/analytics-next': minor
+---
+
+Refactor to use page-tools package

.changeset/wet-waves-pull.md

@@ -0,0 +1,5 @@
+---
+'@segment/analytics-page-tools': major
+---
+
+Release package

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",

packages/browser/.gitignore

@@ -0,0 +1 @@
+umd.old

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",

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."

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'

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.

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'

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()

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) {

packages/config/src/index.js

@@ -1,4 +1,5 @@
 module.exports = {
   createJestTSConfig: require('./jest/config').createJestTSConfig,
   lintStagedConfig: require('./lint-staged/config'),
+  tsupConfig: require('./tsup/config'),
 }

packages/config/src/tsup/config.js

@@ -0,0 +1,12 @@
+const { defineConfig } = require('tsup')
+
+module.exports = defineConfig(() => ({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  dts: {
+    resolve: true,
+    entry: 'src/index.ts',
+  },
+  outDir: 'dist',
+  clean: true,
+}))

packages/page-tools/.eslintrc.js

@@ -0,0 +1,4 @@
+/** @type { import('eslint').Linter.Config } */
+module.exports = {
+  extends: ['../../.eslintrc'],
+}

packages/page-tools/.lintstagedrc.js

@@ -0,0 +1 @@
+module.exports = require("@internal/config").lintStagedConfig

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.

packages/page-tools/README.md

@@ -0,0 +1,3 @@
+# @segment/analytics-page-tools
+
+Browser-only helpers for generating page events with analytics.js. 

packages/page-tools/jest.config.js

@@ -0,0 +1,5 @@
+const { createJestTSConfig } = require('@internal/config')
+
+module.exports = createJestTSConfig(__dirname, {
+  testEnvironment: 'jsdom',
+})

packages/page-tools/package.json

@@ -0,0 +1,39 @@
+{
+  "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/index.mjs",
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js",
+  "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:^"
+  }
+}