[new page] e-commerce guide (withastro#6821)

Co-authored-by: Lloyd Atkinson <[email protected]> Co-authored-by: Kevin Zuniga Cuellar <[email protected]> Co-authored-by: Ricardo Jaime Gil Simões <[email protected]> Co-authored-by: voxel!() <[email protected]> Co-authored-by: Adam Matthiesen <[email protected]> Co-authored-by: Reuben Tier <[email protected]>
tem235 · Feb 29, 2024 · 510c67d · 510c67d
1 parent 8f8bda5
commit 510c67d
Show file tree

Hide file tree

Showing 2 changed files with 196 additions and 0 deletions.
diff --git a/src/content/docs/en/guides/ecommerce.mdx b/src/content/docs/en/guides/ecommerce.mdx
@@ -0,0 +1,195 @@
+---
+title: E-commerce
+description: An introduction to adding e-commerce options to your Astro site
+i18nReady: true
+---
+import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'
+import ReadMore from '~/components/ReadMore.astro'
+
+With Astro, you can build several e-commerce options, from checkout links to hosted payment pages to building an entire storefront using a payment service API.
+
+## Payment processing overlays
+
+Some payment processing services (e.g. [Lemon Squeezy](#lemon-squeezy), [Paddle](#paddle)) add a payment form to allow your customer to purchase from your site. These can be hosted overlays or embedded in a page on your site. These may offer some basic customization or site branding, and may be added to your Astro project as scripts, buttons, or external links.
+
+### Lemon Squeezy
+
+[Lemon Squeezy](https://www.lemonsqueezy.com/) is an all-in-one platform for payments and subscriptions with multi-currency support, global tax compliance, PayPal integration and more. It allows you to create and manage digital products and services through your account dashboard and provides product URLs for the checkout process.
+
+The basic [Lemon.js JavaScript library](https://docs.lemonsqueezy.com/help/lemonjs/what-is-lemonjs) allows you to sell your Lemon Squeezy products with a checkout link.
+
+#### Basic Usage
+
+The following is an example of adding a Lemon Squeezy "Buy now" element to an Astro page. Clicking this link will open a checkout and allow the visitor to complete a single purchase.
+
+1. Add the following `<script>` tag to your page `head` or `body`:
+
+    ```html title="src/pages/my-product-page.astro"
+    <script src="https://app.lemonsqueezy.com/js/lemon.js" defer></script>
+    ```
+2. Create an anchor tag on the page linking to your product URL. Include the class `lemonsqueezy-button` to open a checkout overlay when clicked.
+
+    ```html title="src/pages/my-product-page.astro"
+    <a class="lemonsqueezy-button" href="https://demo.lemonsqueezy.com/checkout/...">
+      Buy Now
+    </a>
+    ```
+
+#### Lemon.js
+
+Lemon.js also provides additional behavior such as [programmatically opening overlays](https://docs.lemonsqueezy.com/help/lemonjs/opening-overlays) and [handling overlay events](https://docs.lemonsqueezy.com/help/lemonjs/opening-overlays).
+
+<ReadMore> Read the [Lemon Squeezy developer getting started guide](https://docs.lemonsqueezy.com/guides/developer-guide) for more information.</ReadMore>
+
+### Paddle
+
+[Paddle](https://www.paddle.com/) is a billing solution for digital products and services. It handles handle payments, taxes, and subscription management through an overlay or inline checkout. 
+
+[Paddle.js](https://developer.paddle.com/paddlejs/overview) is a lightweight JavaScript library that lets you build rich, integrated subscription billing experiences using Paddle.
+
+#### Basic Usage
+
+The following is an example of adding a Paddle "Buy Now" element to an Astro page. Clicking this link will open a checkout and allow the visitor to complete a single purchase.
+
+After your default payment link domain (your own website) is approved by Paddle, you can turn any element on your page into a trigger for a checkout overlay using HTML data attributes.
+
+1. Add the following two `<script>` tags to your page `head` or `body`:
+
+    ```html title="src/pages/my-product-page.astro"
+    <script src="https://cdn.paddle.com/paddle/v2/paddle.js"></script>
+    <script type="text/javascript">
+      Paddle.Setup({ 
+        token: '7d279f61a3499fed520f7cd8c08' // replace with a client-side token
+      });
+    </script>
+    ```
+2. Turn any element on your page into a Paddle Checkout button by adding the `paddle_button` class:
+
+    ```html title="src/pages/my-product-page.astro"
+    <a href='#' class='paddle_button'>Buy Now</a>
+    ```
+3. Add a `data-items` attribute to specify your product's Paddle `priceID` and `quantity`. You can also optionally pass additional [supported HTML data attributes](https://developer.paddle.com/paddlejs/html-data-attributes) to prefill data, handle checkout success, or style your button and checkout overlay:
+
+    ```html title="src/pages/my-product-page.astro"
+    <a 
+      href='#' 
+      class='paddle_button'
+      data-display-mode='overlay'
+      data-theme='light'
+      data-locale='en'
+      data-success-url='https://example.com/thankyou'
+      data-items='[
+        {
+        "priceId": "pri_01gs59hve0hrz6nyybj56z04eq", 
+        "quantity": 1
+        }
+      ]'
+      >
+      Buy now
+    </a>
+    ```
+
+#### Paddle.js
+
+Instead of passing HTML data attributes, you can send data to the checkout overlay using JavaScript for passing multiple attributes and even greater customization. You can also create upgrade workflows using an inline checkout.
+
+<ReadMore>Read more about [using Paddle.js to build an inline checkout](https://developer.paddle.com/build/checkout/build-branded-inline-checkout).</ReadMore>
+
+
+## Full-featured e-commerce solutions
+
+For more customization over your site's shopping cart and checkout process, you can connect a more fully-featured financial service provider (e.g. [Snipcart](#snipcart)) to your Astro project. These e-commerce platforms may also integrate with other third-party services for user account management, personalization, inventory and analytics.
+
+### Snipcart
+
+[Snipcart](https://snipcart.com/) is a powerful, developer-first HTML/JavaScript shopping cart platform.
+
+Snipcart also allows you to integrate with third-party services such as shipping providers, enable webhooks for an advanced e-commerce integration between your shopping cart and other systems, choose from several payment gateways (e.g. Stripe, Paypal, and Square), customize email templates, and even provides live testing environments.
+
+:::tip
+Want a pre-built Snipcart solution instead? Check out [`astro-snipcart`](https://astro-snipcart.vercel.app/), a fully functional Astro community template including an optional design system, ready for you to integrate with your existing Snipcart account.
+:::
+
+#### Basic Usage
+
+The following is an example of configuring a Snipcart checkout and adding button elements for "Add to cart" and "Check out now" to an Astro page. This will allow your visitors to add products to a cart without being immediately sent to a checkout page.
+
+<ReadMore>For complete instructions, including setting up your Snipcart store, please see [the Snipcart installation documentation](https://docs.snipcart.com/v3/setup/installation).</ReadMore>
+
+1. Add the script [as shown in the Snipcart installation instructions](https://docs.snipcart.com/v3/setup/installation) on your page after the `<body>` element.
+    ```html title="src/pages/my-product-page.astro"
+    <body></body>
+    <script>
+      window.SnipcartSettings = {
+        publicApiKey: "YOUR_API_KEY",
+        loadStrategy: "on-user-interaction",
+      };
+
+      (function()...); // available from the Snipcart documentation
+    </script>
+    ```
+
+2. Customize `window.SnipcartSettings` with any of the [available Snipcart settings](https://docs.snipcart.com/v3/setup/installation#setting2) to control the behavior and appearance of your cart.
+
+    ```html title="src/pages/my-product-page.astro"
+    <script>
+      window.SnipcartSettings = {
+        publicApiKey: "YOUR_API_KEY",
+        loadStrategy: "manual",
+        version: "3.7.1",
+        addProductBehavior: "none",
+        modalStyle: "side",
+
+      };
+
+      (function()...); // available from the Snipcart documentation
+    </script>
+    ```
+
+4. Add `class="snipcart-add-item"` to any HTML element, such as a `<button>`, to add an item to the cart when clicked on. Also include any other data elements for [common Snipcart product attributes](https://docs.snipcart.com/v3/setup/products) such as price and description, and any optional fields.
+
+    ```html title="src/pages/my-product-page.astro"
+    <button class="snipcart-add-item"
+      data-item-id="astro-print"
+      data-item-price="39.99"
+      data-item-description="A framed print of the Astro logo."
+      data-item-image="/assets/images/astro-print.jpg"
+      data-item-name="Astro Print"
+      data-item-custom1-name="Frame color"
+      data-item-custom1-options="Brown|Silver[+10.00]|Gold[+20.00]"
+      data-item-custom2-name="Delivery instructions"
+      data-item-custom2-type="textarea">
+      
+      Add to cart
+    </button>
+    ```
+
+6. Add a Snipcart checkout button with the `snipcart-checout` class to open the cart and allow guests to complete their purchase with a checkout modal.
+
+    ```html title="src/pages/my-product-page.astro"
+    <button class="snipcart-checkout">Click here to checkout</button>
+    ```
+
+#### Snipcart JavaScript SDK
+
+The [Snipcart JavaScript SDK](https://docs.snipcart.com/v3/sdk/basics) lets you configure, customize and manage your Snipcart cart programmatically.
+
+This allows you to perform actions such as:
+
+- Retrieve relevant information about the current Snipcart session and apply certain operations to the cart.
+- Listen to incoming events and trigger callbacks dynamically.
+- Listen to state changes and receive a full snapshot of the state of the cart.
+
+<ReadMore>See the [Snipcart documentation](https://docs.snipcart.com/v3/) for more more information about all the options to integrate Snipcart with your Astro Project.</ReadMore>
+
+#### `astro-snipcart`
+
+There are two `astro-snipcart` community packages that can simplify using Snipcart.
+
+- [`@lloydjatkinson/astro-snipcart` Astro template](https://astro-snipcart.vercel.app/): This Astro template includes an optional design system for a complete e-commerce solution out of the box. Learn more on its own extensive documentation site, including [the motivation behind building `astro-snipcart`](https://astro-snipcart.vercel.app/motivation) as providing a convenient, Astro-native way for you to interact with the Snipcart API.
+
+- [`@Adammatthiesen/astro-snipcart` integration](https://github.com/Adammatthiesen/astro-snipcart): This integration was heavily inspired by the `astro-snipcart` theme and provides Astro components (or Vue components) that you can add to your existing Astro project for creating products, controlling the cart, and more. See the [full tutorial](https://matthiesen.xyz/blog/getting-started-with-my-astro-snipcart-addon) for more information.
+
+## Community Resources
+
+- [Hands-On Experience: eCommerce Store with Astro?](https://crystallize.com/blog/building-ecommerce-with-astro)
diff --git a/src/i18n/en/nav.ts b/src/i18n/en/nav.ts
@@ -121,6 +121,7 @@ export default [
 		key: 'guides/internationalization',
 	},
 	{ text: 'Middleware', slug: 'guides/middleware', key: 'guides/middleware' },
+	{ text: 'E-commerce', slug: 'guides/ecommerce', key: 'guides/ecommerce' },
 	{ text: 'Testing', slug: 'guides/testing', key: 'guides/testing' },
 	{ text: 'Authentication', slug: 'guides/authentication', key: 'guides/authentication' },
 	{ text: 'Troubleshooting', slug: 'guides/troubleshooting', key: 'guides/troubleshooting' },