diff --git a/.github/dependabot.yml b/.github/dependabot.yml deleted file mode 100644 index 8f4048d..0000000 --- a/.github/dependabot.yml +++ /dev/null @@ -1,28 +0,0 @@ -version: 2 -updates: - - package-ecosystem: "npm" - directories: - - "/examples" - open-pull-requests-limit: 0 # install only security updates - schedule: - interval: "daily" - commit-message: - prefix: "test(deps):" - groups: - test-deps: - patterns: - - "*" - applies-to: security-updates - - - package-ecosystem: "npm" - directory: "/" - open-pull-requests-limit: 0 # install only security updates - schedule: - interval: "daily" - commit-message: - prefix: "build" - include: scope - groups: - dev-deps: - dependency-type: "development" - applies-to: security-updates diff --git a/CHANGELOG.md b/CHANGELOG.md index c75de6e..867a444 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,7 +12,7 @@ - The SDK api has changed to match changes introduced in V4 version of the agent. - Response field names follow the JavaScript Agent v4 API. For example, `visitorId` is now `visitor_id`, `requestId` is now `event_id`, and other response fields use snake_case. -- The default caching strategy has changed from `sessionStorage` caching to **no caching by default**, aligned with the underlying [JavaScript agent v4 default](https://docs.fingerprint.com/reference/js-agent-v4-start-function#cache). +- The default caching strategy has changed from `sessionStorage` caching to **no caching by default**, aligned with the underlying [JavaScript agent v4 default](https://docs.fingerprint.com/reference/js-agent-start-function#cache). ### Features diff --git a/README.md b/README.md index 21c7da6..0c1a60e 100644 --- a/README.md +++ b/README.md @@ -12,8 +12,8 @@ coverage Current NPM version Monthly downloads from NPM - MIT license - Discord server + MIT license + Discord server Documentation

@@ -69,7 +69,7 @@ pnpm add @fingerprint/react ## Getting started -In order to identify visitors, you'll need a Fingerprint account (you can [sign up for free](https://dashboard.fingerprint.com/signup/)). +In order to identify visitors, you'll need a Fingerprint account (you can [sign up for free](https://dashboard.fingerprint.com/signup)). To get your API key and get started, see the [Fingerprint Quick Start Guide](https://docs.fingerprint.com/docs/quick-start-guide). ### 1. Wrap your application (or component) in ``. @@ -77,8 +77,8 @@ To get your API key and get started, see the [Fingerprint Quick Start Guide](htt - Set `apiKey` to your Fingerprint [Public API Key](https://dashboard.fingerprint.com/api-keys). - Set `region` if you have chosen a non-global [region](https://docs.fingerprint.com/docs/regions) during registration. - Set `endpoints` if you are using [one of our proxy integrations to increase accuracy](https://docs.fingerprint.com/docs/protecting-the-javascript-agent-from-adblockers) and effectiveness of visitor identification. -- You can use all the [start options](https://docs.fingerprint.com/reference/js-agent-v4-start-function#start-options) available in the JavaScript agent `start()` function. -- Caching is disabled by default. To enable caching, pass the JavaScript agent [`cache` start option](https://docs.fingerprint.com/reference/js-agent-v4-start-function#cache). +- You can use all the [start options](https://docs.fingerprint.com/reference/js-agent-start-function#start-options) available in the JavaScript agent `start()` function. +- Caching is disabled by default. To enable caching, pass the JavaScript agent [`cache` start option](https://docs.fingerprint.com/reference/js-agent-start-function#cache). ```jsx // src/index.js @@ -87,12 +87,12 @@ import ReactDOM from 'react-dom/client' import { FingerprintProvider } from '@fingerprint/react' import App from './App' -const root = ReactDOM.createRoot(document.getElementById('app')) +const root = ReactDOM.createRoot(document.getElementById('root')) // supports the same options as `start()` function. root.render( @@ -131,7 +131,7 @@ The `useVisitorData` hook also returns a `getData` method you can use to make an - You can pass `{ immediate: false }` to `useVisitorData` to disable automatic visitor identification on render. -Both `useVisitorData` and `getData` accept all the [get options](https://docs.fingerprint.com/reference/get-function#get-options) available in the JavaScript agent `get` function. +Both `useVisitorData` and `getData` accept all the [get options](https://docs.fingerprint.com/reference/js-agent-get-function#get-options) available in the JavaScript agent `get` function. The returned v4 visitor data uses raw response field names in snake_case, for example `visitor_id` and `event_id`. @@ -209,7 +209,7 @@ function App() { ## Error handling -The `getData` function throws errors directly from the JS Agent without changing them. See [JS Agent error handling](https://docs.fingerprint.com/reference/js-agent-v4-error-handling) for more details. +The `getData` function throws errors directly from the JS Agent without changing them. See [JS Agent error handling](https://docs.fingerprint.com/reference/js-agent-error-handling) for more details. ## API Reference diff --git a/contributing.md b/contributing.md index 27d9948..7825d99 100644 --- a/contributing.md +++ b/contributing.md @@ -1,31 +1,44 @@ -# Contributing to Fingerprint React integration +# Contributing to Fingerprint React SDK ## Working with code -We prefer using [pnpm](https://pnpm.io/) for installing dependencies and running scripts. +We use [pnpm](https://pnpm.io/) for installing dependencies and running scripts. -The main branch is locked for the push action. For proposing changes, use the standard [pull request approach](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). It's recommended to discuss fixes or new functionality in the Issues, first. +The main branch is locked for the push action. For proposing changes, use the standard [pull request approach](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). It's recommended to discuss fixes or new functionality in the Issues first. -### Development playground +### How to build -There are 4 demo pages for this integration: +Just run: -1. In `/examples/create-react-app` folder. It is a rich demo with scenarios of using different caching strategies. You can find more info about configuration and starting demo in the [readme](examples/create-react-app/README.md). -2. In `/examples/next` folder. It is a demo built with NextJS that allows testing SSR scenarios. You can find more info about configuration and starting demo in the [readme](examples/next/README.md). -3. In `/examples/next-appDir` folder. It is the same demo built with NextJS, but with new `app` directory approach. You can find more info about configuration and starting demo in the [readme](examples/next-appDir/README.md). -4. In `/examples/preact` folder. It is a demo built with Preact. You can find more info about configuration and starting demo in the [readme](examples/preact/README.md). -5. In `/examples/webpack-based` folder. It is a simple demo built with raw webpack. +```shell +pnpm install +pnpm build +``` -❗ Build projects before testing integration. First build the `@fingerprint/react` package, and then start any of the example apps. +### Development playground -### How to build +Six demo apps are available: -Just run: +1. [`create-react-app`](examples/create-react-app/README.md) — a rich demo covering different caching strategies. +2. [`next`](examples/next/README.md) — a Next.js demo for testing SSR scenarios. +3. [`next-appDir`](examples/next-appDir/README.md) — the same Next.js demo using the `app` directory. +4. [`preact`](examples/preact/README.md) — a Preact demo. +5. [`vite`](examples/vite/README.md) — a Vite demo. +6. [`webpack-based`](examples/webpack-based/README.md) — a demo using raw webpack. + +Build the SDK before building or starting an example app. From the repository root, run: ```shell pnpm build ``` +Build an example with `pnpm --filter build`, or start it with +`pnpm --filter dev`. + +For example: +```shell +pnpm --filter vite-example dev +``` ### Code style The code style is controlled by [ESLint](https://eslint.org/) and [Prettier](https://prettier.io/). Run to check that the code style is ok: @@ -50,20 +63,36 @@ To run tests you can use IDE instruments or just run: pnpm test ``` +To run tests once with a coverage report: + +```shell +pnpm test:coverage +``` + To check the distributive TypeScript declarations, build the project and run: ```shell pnpm test:dts ``` +### API reference docs + +The API reference is generated from the source with [TypeDoc](https://typedoc.org/). Regenerate it into the (git-ignored) `docs/` folder with: + +```shell +pnpm docs +``` + ### How to publish -The library is automatically released and published to NPM on every push to the main branch if there are relevant changes using [semantic-release](https://github.com/semantic-release/semantic-release) with following plugins: +Releases are managed with [changesets](https://github.com/changesets/changesets). + +When you make a change that should be released, add a changeset to your pull request: + +```shell +pnpm changeset +``` -- [@semantic-release/commit-analyzer](https://github.com/semantic-release/commit-analyzer) -- [@semantic-release/release-notes-generator](https://github.com/semantic-release/release-notes-generator) -- [@semantic-release/changelog](https://github.com/semantic-release/changelog) -- [@semantic-release/npm](https://github.com/semantic-release/npm) -- [@semantic-release/github](https://github.com/semantic-release/github) +This prompts you to select the bump type (`major`, `minor`, or `patch`) and to write a summary that becomes the changelog entry. Commit the generated file in `.changeset/` along with your changes. -The workflow must be approved by one of the maintainers, first. +When PRs with changesets are merged to `main`, the [release workflow](.github/workflows/release.yml) opens (or updates) a "Version Packages" pull request that bumps the version and updates the changelog. Merging that pull request builds the package and publishes it to NPM. diff --git a/examples/create-react-app/README.md b/examples/create-react-app/README.md index 11b51b4..d0e1519 100644 --- a/examples/create-react-app/README.md +++ b/examples/create-react-app/README.md @@ -9,16 +9,22 @@ In order to try out this example: To get the API key: - Go to Fingerprint Dashboard > [API Keys](https://dashboard.fingerprint.com/api-keys) and find it there. -- If you don't have a Fingerprint account, [sign up for free](https://dashboard.fingerprint.com/signup/). +- If you don't have a Fingerprint account, [sign up for free](https://dashboard.fingerprint.com/signup). ### Installing dependencies -1. Go to the root of the project, install dependencies and build it (`cd ../../ && pnpm install && pnpm build`) -2. Come back to the example folder (`cd examples/create-react-app`) and run `pnpm install`. +From the repository root, install dependencies and build the SDK: -After you've completed all the steps and inserted the API key, you can run: +```shell +pnpm install +pnpm build +``` -### `pnpm start` +After setting the API key, start the example: + +```shell +pnpm --filter fingerprintjs-react-spa-example dev +``` Runs the app in the development mode.\ Open [http://localhost:3001](http://localhost:3001) to view it in the browser. diff --git a/examples/create-react-app/package.json b/examples/create-react-app/package.json index c9ffb61..8557c63 100644 --- a/examples/create-react-app/package.json +++ b/examples/create-react-app/package.json @@ -13,7 +13,8 @@ "typescript": "*" }, "scripts": { - "start": "PORT=3001 DISABLE_ESLINT_PLUGIN=true react-scripts start", + "dev": "PORT=3001 DISABLE_ESLINT_PLUGIN=true react-scripts start", + "start": "pnpm dev", "build": "DISABLE_ESLINT_PLUGIN=true react-scripts build" }, "browserslist": { diff --git a/examples/next-appDir/README.md b/examples/next-appDir/README.md index 75c13b6..43d6f0c 100644 --- a/examples/next-appDir/README.md +++ b/examples/next-appDir/README.md @@ -13,16 +13,22 @@ In order to try out this example: To get the API key: - Go to Fingerprint Dashboard > [API Keys](https://dashboard.fingerprint.com/api-keys) and find it there. -- If you don't have a Fingerprint account, [sign up for free](https://dashboard.fingerprint.com/signup/). +- If you don't have a Fingerprint account, [sign up for free](https://dashboard.fingerprint.com/signup). ### Installing dependencies -1. Go to the root of the project, install dependencies and build it (`cd ../../ && pnpm install && pnpm build`) -2. Come back to the example folder (`cd examples/next-appDir`) and run `pnpm install`. +From the repository root, install dependencies and build the SDK: -After you've completed all the steps and inserted the API key, you can run: +```shell +pnpm install +pnpm build +``` -### `pnpm dev` +After setting the API key, start the example: + +```shell +pnpm --filter next-appDir dev +``` Runs the app in the development mode.\ -Open [http://localhost:3002](http://localhost:3002) to view it in the browser. +Open [http://localhost:3003](http://localhost:3003) to view it in the browser. diff --git a/examples/next-appDir/package.json b/examples/next-appDir/package.json index ce23f84..954f1d3 100644 --- a/examples/next-appDir/package.json +++ b/examples/next-appDir/package.json @@ -3,7 +3,7 @@ "version": "0.1.0", "private": true, "scripts": { - "dev": "next dev --port=3002", + "dev": "next dev --port=3003", "build": "next build", "start": "next start", "lint": "next lint" diff --git a/examples/next/README.md b/examples/next/README.md index ccc1377..1bf088d 100644 --- a/examples/next/README.md +++ b/examples/next/README.md @@ -12,16 +12,22 @@ In order to try out this example: To get the API key: - Go to Fingerprint Dashboard > [API Keys](https://dashboard.fingerprint.com/api-keys) and find it there. -- If you don't have a Fingerprint account, [sign up for free](https://dashboard.fingerprint.com/signup/). +- If you don't have a Fingerprint account, [sign up for free](https://dashboard.fingerprint.com/signup). ### Installing dependencies -1. Go to the root of the project, install dependencies and build it (`cd ../../ && pnpm install && pnpm build`) -2. Come back to the example folder (`cd examples/next`) and run `pnpm install`. +From the repository root, install dependencies and build the SDK: -After you've completed all the steps and inserted the API key, you can run: +```shell +pnpm install +pnpm build +``` -### `pnpm dev` +After setting the API key, start the example: + +```shell +pnpm --filter next-example dev +``` Runs the app in the development mode.\ Open [http://localhost:3002](http://localhost:3002) to view it in the browser. diff --git a/examples/preact/README.md b/examples/preact/README.md index 4e8729d..24c248c 100644 --- a/examples/preact/README.md +++ b/examples/preact/README.md @@ -4,22 +4,28 @@ In order to try out this example: -1. Create a `.env` file in this directory. +1. Create a `.env` (or `.env.local`) file in this directory. 2. Set the `PREACT_APP_FPJS_PUBLIC_API_KEY` environment variable to the value of your Fingerprint Public API key. To get the API key: - Go to Fingerprint Dashboard > [API Keys](https://dashboard.fingerprint.com/api-keys) and find it there. -- If you don't have a Fingerprint account, [sign up for free](https://dashboard.fingerprint.com/signup/). +- If you don't have a Fingerprint account, [sign up for free](https://dashboard.fingerprint.com/signup). ### Installing dependencies -1. Go to the root of the project, install dependencies and build it (`cd ../../ && pnpm install && pnpm build`) -2. Come back to the example folder (`cd examples/preact`) and run `pnpm install`. +From the repository root, install dependencies and build the SDK: -After you've completed all the steps and inserted the API key, you can run: +```shell +pnpm install +pnpm build +``` -### `pnpm start` +After setting the API key, start the example: + +```shell +pnpm --filter preact-example dev +``` Runs the app in the development mode.\ Open [http://localhost:8080](http://localhost:8080) to view it in the browser. diff --git a/examples/vite/README.md b/examples/vite/README.md index d2e7761..71a6eb9 100644 --- a/examples/vite/README.md +++ b/examples/vite/README.md @@ -1,73 +1,29 @@ -# React + TypeScript + Vite +# Fingerprint Vite Example -This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules. +This example demonstrates using Fingerprint in a React application built with Vite. -Currently, two official plugins are available: +## Setting up -- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) (or [oxc](https://oxc.rs) when used in [rolldown-vite](https://vite.dev/guide/rolldown)) for Fast Refresh -- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh +### Fingerprint Public API key -## React Compiler +To try this example: -The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation). +1. Create a `.env` or `.env.local` file in this directory. +2. Set `VITE_FPJS_PUBLIC_API_KEY` to your Fingerprint Public API key. -## Expanding the ESLint configuration +Find your API key in the Fingerprint Dashboard under [API Keys](https://dashboard.fingerprint.com/api-keys). If you do not have an account, [sign up for free](https://dashboard.fingerprint.com/signup). -If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules: +### Installing dependencies -```js -export default defineConfig([ - globalIgnores(['dist']), - { - files: ['**/*.{ts,tsx}'], - extends: [ - // Other configs... +From the repository root, install dependencies and build the SDK: - // Remove tseslint.configs.recommended and replace with this - tseslint.configs.recommendedTypeChecked, - // Alternatively, use this for stricter rules - tseslint.configs.strictTypeChecked, - // Optionally, add this for stylistic rules - tseslint.configs.stylisticTypeChecked, - - // Other configs... - ], - languageOptions: { - parserOptions: { - project: ['./tsconfig.node.json', './tsconfig.app.json'], - tsconfigRootDir: import.meta.dirname, - }, - // other options... - }, - }, -]) +```shell +pnpm install +pnpm build ``` -You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules: - -```js -// eslint.config.js -import reactX from 'eslint-plugin-react-x' -import reactDom from 'eslint-plugin-react-dom' +After setting the API key, start the example: -export default defineConfig([ - globalIgnores(['dist']), - { - files: ['**/*.{ts,tsx}'], - extends: [ - // Other configs... - // Enable lint rules for React - reactX.configs['recommended-typescript'], - // Enable lint rules for React DOM - reactDom.configs.recommended, - ], - languageOptions: { - parserOptions: { - project: ['./tsconfig.node.json', './tsconfig.app.json'], - tsconfigRootDir: import.meta.dirname, - }, - // other options... - }, - }, -]) +```shell +pnpm --filter vite-example dev ``` diff --git a/examples/webpack-based/README.md b/examples/webpack-based/README.md index 42eda8c..00f9deb 100644 --- a/examples/webpack-based/README.md +++ b/examples/webpack-based/README.md @@ -13,16 +13,22 @@ In order to try out this example: To get the API key: - Go to Fingerprint Dashboard > [API Keys](https://dashboard.fingerprint.com/api-keys) and find it there. -- If you don't have a Fingerprint account, [sign up for free](https://dashboard.fingerprint.com/signup/). +- If you don't have a Fingerprint account, [sign up for free](https://dashboard.fingerprint.com/signup). ### Installing dependencies -1. Go to the root of the project, install dependencies and build it (`cd ../../ && pnpm install && pnpm build`) -2. Come back to the example folder (`cd examples/webpack-based`) and run `pnpm install`. +From the repository root, install dependencies and build the SDK: -After you've completed all the steps and inserted the API key, you can run: +```shell +pnpm install +pnpm build +``` -### `pnpm dev` +After setting the API key, start the example: + +```shell +pnpm --filter webpack-based dev +``` Runs the app in the development mode.\ Open [http://localhost:8080](http://localhost:8080) to view it in the browser. diff --git a/package.json b/package.json index c9a36f4..ec764b9 100644 --- a/package.json +++ b/package.json @@ -33,7 +33,6 @@ "prepare": "husky install", "watch": "vite build --watch", "build": "vite build", - "start:spa": "pnpm start --prefix=examples/spa", "lint": "eslint --ext .js,.ts,.tsx --ignore-path .gitignore --max-warnings 0 .", "lint:fix": "pnpm lint --fix", "test": "vitest", @@ -54,6 +53,7 @@ }, "author": "FingerprintJS, Inc (https://fingerprint.com)", "license": "MIT", + "packageManager": "pnpm@11.13.0+sha512.88d94724d8f2e6c186744a5584c6e59ecac869ec7ba15e9cb4cd628e8dc7066820b2481d8ee3b51ea8da323a7378068aa58c556a3720d32b7c20a051d088363a", "bugs": { "url": "https://github.com/fingerprintjs/react/issues" }, @@ -62,6 +62,9 @@ "@fingerprint/agent": "^4.0.0", "fast-deep-equal": "3.1.3" }, + "peerDependencies": { + "react": ">=18" + }, "devDependencies": { "@changesets/cli": "^2.30.0", "@commitlint/cli": "^19.2.0", diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index c9e19fa..4bc25c4 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -2,6 +2,12 @@ packages: - examples/* - ./ -onlyBuiltDependencies: - - core-js - - core-js-pure +# pnpm 11 blocks dependency build scripts by default. esbuild powers the Vite +# build, so allow it; the core-js scripts only print funding notices and the +# legacy fsevents@1 native build fails on modern Node (it is optional), so keep +# those disabled. +allowBuilds: + core-js: false + core-js-pure: false + esbuild: true + fsevents: false