DOCSEARCHbyAlgolia
Submit Docs

Basejump Documentation

repository·main·Indexed 21 days ago

https://github.com/usebasejump/basejump

An extension for Supabase Auth that provides a layer for managing personal and team accounts, role-based permissions via Row Level Security (RLS), and integrated billing with Stripe support. It includes utilities for Supabase Edge Functions, such as stripeFunctionHandler and billingWebhooksWrapper, and offers an official Next.js starter template.

Tokens
2.1K
Snippets
6
Records
9
Agent score
76%

What's inside Basejump

  1. What is Basejump?

    main

    Basejump is an extension for Supabase Auth that adds support for personal accounts, team accounts, permissions, and billing.

    Key features include:

    • Personal accounts: Automatically created for every user signing up via Supabase Auth. Billing can be toggled.
    • Team accounts: Shared billable accounts that can be disabled if only personal accounts are desired.
    • Permissions: Managed via Supabase Row Level Security (RLS). Basejump provides convenience methods to restrict row access based on account access and user roles.
    • Billing: Includes out-of-the-box Stripe support, with the ability to add custom providers.

  2. Set up Basejump testing environment

    main

    Basejump uses pgtap for testing. To run the included tests, you must install pgtap, dbdev, and the supabase_test_helpers package.

    Follow these steps in order:

    1. Install the pgtap extension.
    2. Install dbdev following the instructions at database.dev.
    3. Install the basejump-supabase_test_helpers using dbdev.
    4. Execute the tests using the Supabase CLI.
    -- 1. Install pgtap
create extension pgtap with schema extensions;

-- 3. Install supabase_test_helpers
select dbdev.install('basejump-supabase_test_helpers');
    # 4. Run the tests
supabase test db

  3. Use the Basejump Next.js starter template

    main

    If you want a pre-configured Next.js environment for Basejump, you can use the official starter template.

    1. Run the installation command using yarn create next-app.
    2. Note that create-next-app will install the template into a nested directory; you may move the contents to your project root if preferred.
    3. Configure your environment variables by adding your Supabase URL and anon key to a .env.local file (refer to .env.example for the required format).
    yarn create next-app -e https://github.com/usebasejump/basejump-next

  4. Set up Stripe billing handlers for Supabase Edge Functions

    main

    To handle Stripe billing events (like webhooks) within a Supabase Edge Function, use stripeFunctionHandler to create a handler and wrap it with billingFunctionsWrapper to manage security and allowed origins.

    1. Initialize a Stripe client using the Fetch HTTP client (required for Deno/Edge environments).
    2. Create a stripeHandler using stripeFunctionHandler, providing the stripeClient and optional configuration like defaultPlanId and defaultTrialDays.
    3. Wrap the handler with billingFunctionsWrapper to define allowedURLs (the hosts permitted to interact with these endpoints).
    4. Use the resulting billingEndpoint within the serve function of your Edge Function.
    import {serve} from "https://deno.land/std@0.168.0/http/server.ts";
import {billingFunctionsWrapper, stripeFunctionHandler} from "https://deno.land/x/basejump@v2.0.3/billing-functions/mod.ts";
import Stripe from "https://esm.sh/stripe@11.1.0?target=deno";

const stripeClient = new Stripe(Deno.env.get("STRIPE_API_KEY") as string, {
    apiVersion: "2022-11-15",
    httpClient: Stripe.createFetchHttpClient(),
});

const stripeHandler = stripeFunctionHandler({
    stripeClient,
    defaultPlanId: Deno.env.get("STRIPE_DEFAULT_PLAN_ID") as string,
    defaultTrialDays: Deno.env.get("STRIPE_DEFAULT_TRIAL_DAYS") ? Number(Deno.env.get("STRIPE_DEFAULT_TRIAL_DAYS")) : undefined
});

const billingEndpoint = billingFunctionsWrapper(stripeHandler, {
    allowedURLs: ["http://localhost:3000"]
});

serve(async (req) => {
    return await billingEndpoint(req);
});

  5. Implement a Stripe billing webhook handler with billingWebhooksWrapper

    main

    To handle Stripe billing webhooks in a Supabase Edge Function, use the billingWebhooksWrapper and stripeWebhookHandler utilities from the Basejump library.

    1. Initialize a Stripe client using your STRIPE_API_KEY. When running in Deno (Supabase Edge Functions), you must use Stripe.createFetchHttpClient() to ensure compatibility with the Fetch API.
    2. Create a stripeResponse by calling stripeWebhookHandler with your stripeClient and your STRIPE_WEBHOOK_SIGNING_SECRET.
    3. Wrap that response using billingWebhooksWrapper to create the final webhookEndpoint.
    4. Serve the webhookEndpoint using the Deno serve function.

    Required Environment Variables:

    • STRIPE_API_KEY: Your Stripe secret API key.
    • STRIPE_WEBHOOK_SIGNING_SECRET: The signing secret provided by Stripe for your webhook endpoint.
    import {serve} from "https://deno.land/std@0.168.0/http/server.ts";
import {billingWebhooksWrapper, stripeWebhookHandler} from "https://deno.land/x/basejump@v2.0.3/billing-functions/mod.ts";
import Stripe from "https://esm.sh/stripe@11.1.0?target=deno";

const stripeClient = new Stripe(Deno.env.get("STRIPE_API_KEY") as string, {
    apiVersion: "2022-11-15",
    httpClient: Stripe.createFetchHttpClient(),
});

const stripeResponse = stripeWebhookHandler({
    stripeClient,
    stripeWebhookSigningSecret: Deno.env.get("STRIPE_WEBHOOK_SIGNING_SECRET") as string,
});

const webhookEndpoint = billingWebhooksWrapper(stripeResponse);

serve(async (req) => {
    const response = await webhookEndpoint(req);
    return response;
});

  6. Configure ALLOWED_HOST for Stripe billing portal

    main

    The ALLOWED_HOST environment variable determines which hostnames are permitted to be used as return URLs when redirecting users back from the Stripe billing portal.

    Note: If you need to support multiple allowed hosts, you may need to add them directly within the billing-functions function code.

    ALLOWED_HOST=http://localhost:3000

  7. Configure Stripe environment variables

    main

    If you are using Stripe for billing, you must configure the following environment variables in your Supabase functions environment. These keys are used to authenticate with Stripe, identify default pricing, and manage trial periods.

    STRIPE_API_KEY=sk_test_asdf
STRIPE_WEBHOOK_SIGNING_SECRET=whsec_asdf
STRIPE_DEFAULT_PLAN_ID=price_asdf
STRIPE_DEFAULT_TRIAL_DAYS=30