# 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, and data storage. The primary SDK is `@memberstack/dom` which works with any JavaScript framework.

For comprehensive documentation with full code examples, see [llms-full.txt](https://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

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

## 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
- [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