# Memberstack

> Memberstack is a membership and authentication platform for websites. It provides user authentication, gated content, subscription payments via Stripe, and data storage - all without backend code. 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

**DEPRECATED PACKAGES**: `@memberstack/react` and `@memberstack/nextjs` are deprecated and maintained for legacy customers only. 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

## Quick Start

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

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

## Core Concepts

- **Members**: End users who sign up/login (NOT "users" - that's app owners)
- **Plans**: Access tiers (free or paid via Stripe) that control what members can access
- **Gated Content**: Content restricted by plan - show/hide 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
- **Member JSON**: Flexible JSON storage per member (no predefined schema)
- **Data Tables**: Structured relational data with querying and access control

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

## 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
- `getMemberToken()`: Get JWT token for authenticated API requests
- `loginWithProvider({ provider })`: OAuth login (redirects immediately)
- `signupWithProvider({ provider, plans? })`: OAuth signup (redirects immediately)
- `sendMemberLoginPasswordlessEmail({ email })`: Send magic link for login
- `loginMemberPasswordless({ email, passwordlessToken })`: Complete magic link login
- `sendMemberResetPasswordEmail({ email })`: Send password reset email
- `resetMemberPassword({ token, newPassword })`: Reset password with token

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

## 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 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, 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.hideModal();
```

## 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="pln_your-plan-id"` - Show only to members with specific plan

**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="prc_your-price-id"` - Stripe checkout button

**Display Member Info**:
- `data-ms-member="email"` - Show member's email
- `data-ms-member="first-name"` - 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
- [Webflow Help Center](https://docs.memberstack.com/hc/en-us): Data attributes reference
- [Data Tables Guide](https://developers.memberstack.com/admin-rest-api/data-tables): Structured data storage

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