README.md

Stripe Examples For ApostropheCMS

These modules add client-side integration examples for Stripe packages to page types in ApostropheCMS. One example primarily uses Alpine.js, while the other is mostly written in Vanilla JS with sprinkles of HTMX/hyperscript.

The Stripe-ApostropheCMS packages used in these examples are:

• apostrophe-stripe-checkout
• apostrophe-stripe-products

Alpine.js example screenshots

HTMX + Vanilla JS example screenshots

Installation

Use your preferred package manager to install the following packages:

npm install stripe-examples@npm:@stepanjakl/apostrophe-stripe-examples

npm install stripe-checkout@npm:@stepanjakl/apostrophe-stripe-checkout

npm install stripe-products@npm:@stepanjakl/apostrophe-stripe-products

npm install read-only-field@npm:@stepanjakl/apostrophe-read-only-field

Usage

First, add installed modules to your configuration in the app.js root file:

require('apostrophe')({
  shortName: 'project-name',
  modules: {
    // Custom fields
    'read-only-field': {},

    // Stripe Checkout
    'stripe-checkout': {},
    'stripe-checkout/session': {},

    // Stripe Products
    'stripe-products': {},
    'stripe-products/product': {},

    // Stripe Examples
    'stripe-examples': {},
    'stripe-examples/example-alpine-page': {},
    'stripe-examples/example-htmx-vanilla-js-page': {}
  }
});

Then, set global variables inside the .env file. It's important to set the STRIPE_TEST_MODE variable to anything other than false to enable test mode.

PORT='4000'
APOS_BASE_URL='http://localhost:4000'
APOS_RELEASE_ID='a4-boilerplate'
APOS_MONGODB_URI='mongodb://localhost:27017/a4-boilerplate'

STRIPE_KEY='sk_test_xyz'
STRIPE_TEST_MODE='false'
STRIPE_DASHBOARD_BASE_URL='https://dashboard.stripe.com'
STRIPE_WEBHOOK_ENDPOINT_SECRET='whsec_xyz'

---

To run these examples with the fully functional stripe-checkout module, you'll need to set up event forwarding using the Stripe CLI. This will send all Stripe events to your local webhook endpoint for testing and/or monitoring purposes.

Here's how to do it:

1. Set up event forwarding with the Stripe CLI: Run the following command to listen for specific events and forward them to your local endpoint:

   stripe listen --events=payment_intent.succeeded --forward-to localhost:5000/api/v1/stripe-checkout/webhook

2. Set the webhook signing secret: The webhook signing secret is generated and displayed in the initial output of the listen command. Use this value for the STRIPE_WEBHOOK_ENDPOINT_SECRET environment variable.

For more details on creating a secret Stripe API key, read the documentation.

---

Lastly, to activate the example page types, integrate them into the core module configuration located at modules/@apostrophecms/page/index.js:

module.exports = {
  options: {
    types: [
      {
        name: 'default-page',
        label: 'Default'
      },
      {
        name: '@apostrophecms/home-page',
        label: 'Home'
      },
      {
        name: 'stripe-examples/example-alpine-js-page',
        label: 'Stripe - Example with Alpine.js'
      },
      {
        name: 'stripe-examples/example-htmx-vanilla-js-page',
        label: 'Stripe - Example with HTMX + Vanilla JS'
      }
    ]
  }
};

Separation of concerns

The decision to keep the products and checkout packages separate aligns with the principle of separation of concerns. Stripe's API structure exemplifies this approach, offering distinct endpoints for Products and Checkout Sessions (Stripe API Documentation).

Each package is designed to function independently, allowing for flexible integration. For instance, you can use the stripe-checkout package with your existing product dataset without requiring additional dependencies (as outlined here). This modular approach also facilitates the integration of other Stripe services into the Stripe/Apostrophe ecosystem without impacting existing functionality.

Moreover, maintaining separate packages simplifies updates, maintenance, and troubleshooting, ensuring a more manageable and robust development process.

Additional Stripe packages to support other Stripe services can be added upon request. For inquiries, please email: stepan.jakl@outlook.com.