# Memberstack

> Memberstack is a content gating, membership and authentication platform for any website. Used by 100,000 Webflow users. It provides user authentication, gated content, subscription payments via Stripe, data storage, and email campaigns to members (Beta). The primary SDK is `@memberstack/dom` which works with any JavaScript framework.

For comprehensive documentation with full code examples, see [llms-full.txt](https://www.memberstack.com/llms-full.txt).

## Critical Information

Use `@memberstack/dom` directly with React, Next.js, Vue, Svelte, or any JavaScript framework. 

**Client-Side**: `@memberstack/dom` (npm install @memberstack/dom) - Primary SDK for all JavaScript frameworks
**Server-Side**: `@memberstack/admin` (npm install @memberstack/admin) - Node.js package for backend operations
**Webflow**: `@memberstack/webflow` loaded via script tag (not npm) - Data attributes, no coding required
**AI Tools**: MCP Server for Claude Code, Cursor, Codex integration

**DEPRECATED PACKAGES**: `@memberstack/react` and `@memberstack/nextjs` are deprecated and maintained for legacy customers only. 

## Quick Start

### JavaScript / npm (React, Next.js, Vue, Svelte, etc.)

```javascript
import memberstackDOM from '@memberstack/dom';

const memberstack = memberstackDOM.init({
  publicKey: 'pk_your_public_key_here',  // REQUIRED
  useCookies: true  // Optional: enable cookie-based auth
});
```

### Webflow (no coding required)

Add the Memberstack script tag to your Webflow project. This is auto-generated in the Memberstack dashboard — no npm install needed.

```html
<script data-memberstack-app="YOUR_APP_ID" src="https://static.memberstack.com/scripts/v2/memberstack.js" type="text/javascript"></script>
```

This creates a global `window.$memberstackDom` object with the same methods as the `@memberstack/dom` npm package. Webflow users interact via `data-ms-*` attributes instead of JavaScript — see the Webflow Integration section below.

## Core Concepts

- **Members**: End users who sign up/login
- **Users**: Memberstack customers and site admin
- **Plans**: Access tiers (free or paid) that control what members can access
- **Gated Content**: Content restricted by plan - show/hide pages, folders, or page elements based on membership status or specific plans
- **Plan IDs** (`pln_*`): Used for free plans
- **Price IDs** (`prc_*`): Used for paid plans with Stripe checkout
- **Custom Fields**: Predefined in dashboard, stored as strings. Limit 100 fields. 
- **Member JSON**: 1mb of flexible JSON storage per member (no predefined schema)
- **Data Tables**: Structured relational data with querying and access control
- **Email Campaigns** (Beta): Send one-to-many broadcast emails (newsletters, announcements) to members from the dashboard — distinct from automated transactional emails

## Authentication Methods

- `loginMemberEmailPassword({ email, password })`: Email/password login
- `signupMemberEmailPassword({ email, password, customFields?, plans? })`: Email/password signup. Plans must be `[{ planId: "pln_..." }]`
- `logout()`: Sign out current member
- `getCurrentMember()`: Get current authenticated member or null
- `onAuthChange(callback)`: Subscribe to auth state changes. Returns `{ unsubscribe }` - always call on unmount
- `getMemberCookie()`: Get JWT token for authenticated API requests
- `loginWithProvider({ provider })`: OAuth login (redirects immediately)
- `signupWithProvider({ provider, plans? })`: OAuth signup (redirects immediately)
- `sendMemberLoginPasswordlessEmail({ email })`: Send 6 digit token for login
- `signupMemberPasswordless({ email, passwordlessToken })`: Complete 6 digit token login
- `loginMemberPasswordless({ email, passwordlessToken })`: Complete 6 digit token login
- `sendMemberSignupPasswordlessEmail({ email })`: Send 6 digit token for signup

## Profile Management

- `updateMember({ customFields })`: Update member's custom fields
- `updateMemberAuth({ email?, oldPassword?, newPassword? })`: Update email or password
- `getMemberJSON()`: Get member's JSON data. Returns `{ data: { json: object | null } }`
- `updateMemberJSON({ json })`: **REPLACES** all JSON data. Fetch first, merge, then update.
- `deleteMember()`: Delete member account
- `sendMemberResetPasswordEmail({ email })`: Send password reset email
- `resetMemberPassword({ token, newPassword })`: Reset password with token

## Plan & Payment Management

- `getPlans()`: Get all available plans
- `getPlan({ planId })`: Get single plan details
- `addPlan({ planId })`: Add free plan to member (use Plan ID `pln_*`)
- `removePlan({ planId })`: Remove free plan from member
- `purchasePlansWithCheckout({ priceId, successUrl?, cancelUrl? })`: Stripe checkout (use Price ID `prc_*`)
- `launchStripeCustomerPortal({ returnUrl? })`: Open Stripe billing portal

## Data Tables

- `getDataTables()`: List all tables
- `getDataTable({ table })`: Get table schema and info
- `createDataRecord({ table, data })`: Create new record
- `getDataRecord({ table, recordId })`: Get single record
- `updateDataRecord({ recordId, data })`: Partial update (unlike Member JSON)
- `deleteDataRecord({ recordId })`: Delete record
- `queryDataRecords({ table, query })`: Advanced querying with filters, sorting, pagination, includes

**Rate Limits**: Creates 10/min, Reads 25/sec, Writes 30/min, Global 200/30sec

## Pre-built Modals

```javascript
memberstack.openModal("LOGIN");
memberstack.openModal("SIGNUP", { signup: { plans: ["pln_free-id"] } });  // Note: array of strings, not objects
memberstack.openModal("PROFILE");
memberstack.openModal("FORGOT_PASSWORD");
memberstack.openModal("RESET_PASSWORD");
memberstack.hideModal();
```

## Critical Gotchas

1. **updateMemberJSON() REPLACES data completely** - it does NOT merge. Always fetch first, merge, then update.
2. **Modal vs Method parameters differ**: Methods use `plans: [{ planId: "pln_..." }]`, Modals use `signup: { plans: ["pln_..."] }`
3. **Member properties**: Use `member.auth.email` (NOT `member.data.email`), `member.planConnections` (NOT `member.plans`)
4. **Provider auth redirects immediately** - code after `loginWithProvider()` won't execute

## Framework Integration

All frameworks should use `@memberstack/dom` directly:

**React**: Initialize in useEffect, store in state
**Vue**: Initialize in onMounted
**Svelte/SvelteKit**: Initialize in onMount
**Next.js**: Initialize client-side only (not in SSR)

## Webflow Integration

**For Webflow users: Use data attributes - no coding required.** The `@memberstack/webflow` package is automatically loaded and handles everything through simple HTML attributes you add in Webflow's Designer.

**Gated Content** (show/hide based on membership):
- `data-ms-content="members"` - Show only to logged-in members
- `data-ms-content="!members"` - Show only to logged-out visitors
- `data-ms-content="your-content-id"` - Show only to members with access
- `data-ms-content="!your-content-id"` - Show only to members without access

**Forms** (add to any Webflow form):
- `data-ms-form="login"` - Login form
- `data-ms-form="signup"` - Signup form
- `data-ms-form="profile"` - Profile update form
- `data-ms-form="forgot-password"` - Password reset request

**Buttons**:
- `data-ms-action="logout"` - Log member out
- `data-ms-modal="login"` / `data-ms-modal="signup"` - Open pre-built modals
- `data-ms-price:add="prc_your-price-id"` - Stripe checkout/upgrade button to add a paid plan
- `data-ms-price:update="prc_your-price-id"` - Stripe checkout button to replace a paid plan
- `data-ms-plan:add="pln_your-free-plan-id"` - Add a free plan
- `data-ms-plan:remove="pln_your-free-plan-id"` - Remove a free plan

**Display Member Info**:
- `data-ms-member="email"` - Show member's email
- `data-ms-member="your_field_id"` - Show custom field value

## Server-Side Admin Package

**Package**: `@memberstack/admin` (npm install @memberstack/admin)
**Use Case**: Server-side member management, token verification, webhook handling

```javascript
import memberstackAdmin from '@memberstack/admin';
const memberstack = memberstackAdmin.init('sk_your_secret_key');  // Secret key, NOT public key
```

**Key Methods**:
- `memberstack.members.list({ limit?, after?, order? })`: List members with pagination
- `memberstack.members.retrieve({ id })`: Get single member by ID
- `memberstack.members.create({ email, password, plans?, customFields?, json? })`: Create member
- `memberstack.members.update({ id, data: { email?, customFields?, json? } })`: Update member
- `memberstack.members.delete({ id })`: Delete member
- `memberstack.members.addFreePlan({ id, data: { planId } })`: Add free plan
- `memberstack.members.removeFreePlan({ id, data: { planId } })`: Remove free plan
- `memberstack.verifyToken({ token, audience? })`: Verify JWT token from DOM package
- `memberstack.verifyWebhookSignature({ payload, headers, secret })`: Verify webhook authenticity

**Important**: Never expose secret keys in client-side code. Use `sk_sb_*` for sandbox, `sk_*` for live.

## Email Campaigns (Beta)

**Dashboard feature, not an SDK/API method.** Email Campaigns let users compose and send one-to-many broadcast emails (newsletters, product announcements, re-engagement, onboarding) to their members directly from the Memberstack dashboard. There is currently no `@memberstack/dom` or `@memberstack/admin` method to create or send campaigns — it is managed in the dashboard under **Emails**. This is distinct from transactional emails (automated one-to-one messages like password resets and one-time login codes).

**Status**: Beta. Features and pricing may change.

**Key capabilities**:
- Drag-and-drop email builder with editable pre-designed templates
- Merge tags for personalization: member email, member ID, app name, current year, and custom fields
- Audience targeting: by plan and status (Active, Trialing, Requires Payment, Canceled), by custom field (operators: Equals, Contains, Starts with, Not equals), by signup date, last login, or email-verified status — or send to all members
- Send now or schedule for later; campaigns can be paused, resumed, canceled, or duplicated
- Real-time analytics: delivered, opened, clicked, bounced, complained, unsubscribed, plus per-recipient detail
- Automatic compliant footer (Unsubscribe + View in browser) on every send — not optional. Unsubscribed members are skipped automatically and still receive transactional emails

**Requirements & limits**:
- A verified sender domain (custom domain required; free providers like gmail.com cannot be used as the "from" address)
- An active paid plan with available email quota (not available on free accounts)
- Account at least 7 days old, and at least one member to send to
- Capped at 15,000 recipients per send (contact support to go higher)
- Rate limit of one campaign per hour
- Monthly email quota anchored to the billing cycle; paid add-ons are available for additional sending capacity
- Bounce/complaint rates are monitored mid-send; a campaign auto-stops if they get too high

## MCP Server (AI Integration)

**Beta Feature**: Connect AI tools like Claude Code, Cursor, or Codex directly to your Memberstack projects.

**Installation (Claude Code)**:
```bash
claude mcp add memberstack --scope user npx mcp-remote https://mcp.memberstack.com/mcp
```

**What it does**: ~68 tools for natural language interaction with Memberstack:
- Manage members, plans, and data tables
- Configure gated content and access rules
- Switch between SANDBOX and LIVE environments
- Search Memberstack documentation

**Example prompts**:
- "List my Memberstack apps"
- "Create a new member with email test@example.com"
- "Show me all members on the Pro plan"
- "Switch to SANDBOX environment"

**Authentication**: OAuth 2.1 with PKCE - credentials never shared with AI client.

## Docs

- [DOM Package Documentation](https://developers.memberstack.com/dom-package): Full API reference
- [Admin Package Documentation](https://developers.memberstack.com/admin-node-package): Server-side API
- [MCP Server Documentation](https://developers.memberstack.com/mcp-server): AI integration guide
- [Memberstack Help Center](https://docs.memberstack.com/hc/en-us): Complete product documentation
- [Email Campaigns: A Complete Guide](https://docs.memberstack.com/hc/en-us/articles/50930347839387-Email-Campaigns-A-Complete-Guide): Full guide to the Email Campaigns (Beta) feature
- [Data Tables Guide](https://developers.memberstack.com/admin-rest-api/data-tables): Structured data storage
- [@memberstack/dom on npm](https://www.npmjs.com/package/@memberstack/dom): Client-side SDK package
- [@memberstack/admin on npm](https://www.npmjs.com/package/@memberstack/admin): Server-side SDK package

## Optional

- [Legacy React Package](https://www.npmjs.com/package/@memberstack/react): DEPRECATED - use @memberstack/dom
- [Legacy Next.js Package](https://www.npmjs.com/package/@memberstack/nextjs): DEPRECATED - use @memberstack/dom