{"id":27614,"library":"better-auth-openmeter-plugin","title":"Better Auth OpenMeter Plugin","description":"Better Auth plugin for OpenMeter usage metering, entitlements, API key tracking, organization customers, React hooks, and billing provider bridges (Stripe, Polar, Razorpay, Creem, Dodo Payments, Autumn). Current stable version 0.5.0, released monthly. Key differentiators: seamless OpenMeter integration with Better Auth auth lifecycle, support for both greenfield runtime and catalog/helper modes, built-in billing catalog DSL with recurring-first plans/add-ons/top-ups, and provider-aware compilation for multiple billing providers.","status":"active","version":"0.5.0","language":"javascript","source_language":"en","source_url":"https://github.com/kaustubhkagrawal/better-auth-openmeter-plugin","tags":["javascript","better-auth","better-auth-plugin","openmeter","usage-metering","entitlements","usage-based-billing","metering","billing"],"install":[{"cmd":"npm install better-auth-openmeter-plugin","lang":"bash","label":"npm"},{"cmd":"yarn add better-auth-openmeter-plugin","lang":"bash","label":"yarn"},{"cmd":"pnpm add better-auth-openmeter-plugin","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for interacting with the OpenMeter API","package":"@openmeter/sdk","optional":false},{"reason":"Peer dependency for Better Auth core types and functionality","package":"@better-auth/core","optional":false},{"reason":"Peer dependency for the Better Auth server package","package":"better-auth","optional":false},{"reason":"Peer dependency for React Query hooks","package":"react","optional":true},{"reason":"Peer dependency for React Query hooks","package":"@tanstack/react-query","optional":true}],"imports":[{"note":"Named export only. Default export does not exist.","wrong":"import openmeterPlugin from 'better-auth-openmeter-plugin'","symbol":"openmeterPlugin","correct":"import { openmeterPlugin } from 'better-auth-openmeter-plugin'"},{"note":"Client plugin is a separate subpath export. Import from the /client path.","wrong":"import { openmeterClientPlugin } from 'better-auth-openmeter-plugin'","symbol":"openmeterClientPlugin","correct":"import { openmeterClientPlugin } from 'better-auth-openmeter-plugin/client'"},{"symbol":"applyCatalogTopupGrant","correct":"import { applyCatalogTopupGrant } from 'better-auth-openmeter-plugin'"},{"note":"OpenMeter SDK client is from the separate @openmeter/sdk package.","wrong":"import { OpenMeter } from 'better-auth-openmeter-plugin'","symbol":"OpenMeter","correct":"import { OpenMeter } from '@openmeter/sdk'"}],"quickstart":{"code":"import { betterAuth } from 'better-auth';\nimport { openmeterPlugin } from 'better-auth-openmeter-plugin';\n\nconst auth = betterAuth({\n  plugins: [\n    openmeterPlugin({\n      apiKey: process.env.OPENMETER_API_KEY ?? '',\n      baseUrl: 'https://openmeter.cloud',\n      createCustomerOnSignUp: true,\n      syncCustomerOnUserUpdate: true,\n      trackAuthEvents: true,\n      customer: {\n        resolveKey: ({ user }) => user.id,\n        resolveSubject: ({ user }) => user.id,\n        resolveProfile: ({ user, defaults }) => ({\n          ...defaults,\n          description: `Better Auth user ${user.id}`,\n          billingAddress: {\n            country: 'US',\n          },\n          metadata: {\n            ...defaults.metadata,\n            source: 'better-auth',\n          },\n        }),\n      },\n    }),\n  ],\n});","lang":"typescript","description":"Server-side setup of Better Auth with the OpenMeter plugin, including customer creation on sign-up and event tracking."},"warnings":[{"fix":"Run your Better Auth migration/generation step after adding the plugin to your auth config.","message":"The plugin modifies the Better Auth user schema to add an openmeterCustomerId field. You must run a database migration after enabling the plugin to create this column.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Update plugin configuration to use the catalog DSL: define plans with recurring, add-ons, and top-ups as described in the README.","message":"In v0.3.0, the billing catalog DSL was introduced with a different shape for plans and add-ons. If you used an earlier version without the catalog, you will need to refactor your billing configuration.","severity":"breaking","affected_versions":"<0.3.0"},{"fix":"Use import { openmeterClientPlugin } from 'better-auth-openmeter-plugin/client'.","message":"The client plugin import path changed. In v0.3.0 and earlier, client plugin was available at 'better-auth-openmeter-plugin/client'.","severity":"deprecated","affected_versions":"<0.4.0"},{"fix":"Ensure your project runs on Node >=20 and uses ESM (type: 'module' in package.json).","message":"The package requires Node.js >=20 and only supports ESM. Using require() or older Node versions will break.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Explicitly set baseUrl to your OpenMeter instance URL (e.g., https://openmeter.cloud or http://127.0.0.1:8888 for local dev).","message":"The OpenMeter client must be configured with a valid API key or base URL. Passing only an apiKey without baseUrl defaults to https://openmeter.cloud, which may not be appropriate for all environments.","severity":"gotcha","affected_versions":">=0.0.0"}],"env_vars":null,"last_verified":"2026-05-09T00:00:00.000Z","next_check":"2026-08-07T00:00:00.000Z","problems":[{"fix":"Update to v0.4.0 or later: npm install better-auth-openmeter-plugin@latest","cause":"Using an older version of the package that does not have the /client subpath export.","error":"Cannot find module 'better-auth-openmeter-plugin/client'"},{"fix":"Use import { openmeterPlugin } from 'better-auth-openmeter-plugin'","cause":"Importing the module as default import instead of named import.","error":"TypeError: openmeterPlugin is not a function"},{"fix":"Run your database migration (e.g., npx better-auth generate && npx better-auth migrate) to add the openmeterCustomerId column.","cause":"Database schema has not been migrated after enabling the plugin.","error":"The field 'openmeterCustomerId' does not exist on type 'User'"},{"fix":"Ensure OPENMETER_API_KEY environment variable is set and valid. In local dev, use openmeterClient with a mock or local server.","cause":"The provided apiKey is incorrect or missing.","error":"OpenMeterError: unauthorized - invalid API key"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}