<Twitter Title>

Additional Guides: guides to e-commerce, authentication, testing, and digital asset management in Astro projects # Authentication > An intro to authentication in Astro Authentication and authorization are two security processes that manage access to your website or app. Authentication verifies a visitor’s identity, while authorization grants access to protected areas and resources. Authentication allows you to customize areas of your site for logged-in individuals and provides the greatest protection for personal or private information. Authentication libraries (e.g. [Auth.js](https://authjs.dev/), [Clerk](https://clerk.com)) provide utilities for multiple authentication methods such as email sign-in and OAuth providers. See how to [add authentication with Supabase](/en/guides/backend/supabase/#adding-authentication-with-supabase) or [add authentication with Firebase](/en/guides/backend/google-firebase/#adding-authentication-with-firebase) in our dedicated guides for these backend services. ## Auth.js [Section titled “Auth.js”](#authjs) Auth.js is a framework agnostic solution for authentication. A community framework adapter [`auth-astro`](https://www.npmjs.com/package/auth-astro) is available for Astro. ### Installation [Section titled “Installation”](#installation) Use the `astro add` command for your preferred package manager to add the `auth-astro` integration to an Astro project configured with a [server adapter](/en/guides/on-demand-rendering/#server-adapters) for on-demand rendering. * npm ```shell npx astro add auth-astro ``` * pnpm ```shell pnpm astro add auth-astro ``` * Yarn ```shell yarn astro add auth-astro ``` #### Manual installation [Section titled “Manual installation”](#manual-installation) To install `auth-astro` manually, install the required package for your package manager: * npm ```shell npm install auth-astro @auth/core@^0.18.6 ``` * pnpm ```shell pnpm add auth-astro @auth/core@^0.18.6 ``` * Yarn ```shell yarn add auth-astro @auth/core@^0.18.6 ``` Then, apply the integration to your `astro.config.*` file using the `integrations` property: astro.config.mjs ```diff import { defineConfig } from 'astro/config'; import netlify from '@astrojs/netlify'; +import auth from 'auth-astro'; export default defineConfig({ // ... adapter: netlify(), + integrations: [auth()], }); ``` ### Configuration [Section titled “Configuration”](#configuration) Create an `auth.config.ts` file in your project’s root directory. Add any auth [providers](https://authjs.dev/getting-started/providers) or methods you wish to support, along with any environment variables they require. auth.config.ts ```ts import GitHub from '@auth/core/providers/github'; import { defineConfig } from 'auth-astro'; export default defineConfig({ providers: [ GitHub({ clientId: import.meta.env.GITHUB_CLIENT_ID, clientSecret: import.meta.env.GITHUB_CLIENT_SECRET, }), ], }); ``` Create a `.env` file in the root of your project if it does not already exist. Add the following two environment variables. `AUTH_SECRET` should be a private string with a minimum of 32 characters. .env ```sh AUTH_TRUST_HOST=true AUTH_SECRET= ``` ### Usage [Section titled “Usage”](#usage) You can add sign-in and sign-out buttons using the `auth-astro/client` module in a script tag or client-side framework component. src/pages/index.astro ```astro --- import Layout from 'src/layouts/Base.astro'; --- ``` You can fetch the user’s session using the `getSession` method. src/pages/index.astro ```astro --- import Layout from 'src/layouts/Base.astro'; import { getSession } from 'auth-astro/server'; export const prerender = false; // Not needed in 'server' mode const session = await getSession(Astro.request); --- { session ? (

Welcome {session.user?.name}

) : (

Not logged in

) } ``` ### Next Steps [Section titled “Next Steps”](#next-steps) * [`auth-astro` on GitHub](https://github.com/nowaythatworked/auth-astro?tab=readme-ov-file#auth-astro) * [Auth.js documentation](https://authjs.dev/) ## Better Auth [Section titled “Better Auth”](#better-auth) Better Auth is a framework-agnostic authentication (and authorization) framework for TypeScript. It provides a comprehensive set of features out of the box and includes a plugin ecosystem that simplifies adding advanced functionalities. It supports Astro out of the box, and you can use it to add authentication to your astro project. ### Installation [Section titled “Installation”](#installation-1) * npm ```shell npm install better-auth ``` * pnpm ```shell pnpm add better-auth ``` * Yarn ```shell yarn add better-auth ``` For detailed setup instructions, check out the [Better Auth Installation Guide](https://www.better-auth.com/docs/installation). ### Configuration [Section titled “Configuration”](#configuration-1) Configure your database table to store user data and your preferred authentication methods as described in the [Better Auth Installation Guide](https://www.better-auth.com/docs/installation#configure-database). Then, you’ll need to mount the Better Auth handler in your Astro project. src/pages/api/auth/\[...all].ts ```ts import { auth } from "../../../lib/auth"; // import your Better Auth instance import type { APIRoute } from "astro"; export const prerender = false; // Not needed in 'server' mode export const ALL: APIRoute = async (ctx) => { return auth.handler(ctx.request); }; ``` Follow the [Better Auth Astro Guide](https://www.better-auth.com/docs/integrations/astro) to learn more. ### Usage [Section titled “Usage”](#usage-1) Better Auth offers a `createAuthClient` helper for various frameworks, including Vanilla JS, React, Vue, Svelte, and Solid. For example, to create a client for React, import the helper from `'better-auth/react'`: * React src/lib/auth-client.ts ```ts import { createAuthClient } from 'better-auth/react'; export const authClient = createAuthClient(); export const { signIn, signOut } = authClient; ``` * Solid src/lib/auth-client.ts ```ts import { createAuthClient } from 'better-auth/solid'; export const authClient = createAuthClient(); export const { signIn, signOut } = authClient; ``` * Svelte src/lib/auth-client.ts ```ts import { createAuthClient } from 'better-auth/svelte'; export const authClient = createAuthClient(); export const { signIn, signOut } = authClient; ``` * Vue src/lib/auth-client.ts ```ts import { createAuthClient } from 'better-auth/vue'; export const authClient = createAuthClient(); export const { signIn, signOut } = authClient; ``` Once your client is set up, you can use it to authenticate users in your Astro components or any framework-specific files. The following example adds the ability to log in or log out with your configured `signIn()` and `signOut()` functions. src/pages/index.astro ```astro --- import Layout from 'src/layouts/Base.astro'; --- ``` You can then use the `auth` object to get the user’s session data in your server-side code. The following example personalizes page content by displaying an authenticated user’s name: src/pages/index.astro ```astro --- import { auth } from "../../../lib/auth"; // import your Better Auth instance export const prerender = false; // Not needed in 'server' mode const session = await auth.api.getSession({ headers: Astro.request.headers, }); ---

{session.user?.name}

``` You can also use the `auth` object to protect your routes using middleware. The following example checks whether a user trying to access a logged-in dashboard route is authenticated, and redirects them to the home page if not. src/middleware.ts ```ts import { auth } from "../../../auth"; // import your Better Auth instance import { defineMiddleware } from "astro:middleware"; export const onRequest = defineMiddleware(async (context, next) => { const isAuthed = await auth.api .getSession({ headers: context.request.headers, }) if (context.url.pathname === "/dashboard" && !isAuthed) { return context.redirect("/"); } return next(); }); ``` ### Next Steps [Section titled “Next Steps”](#next-steps-1) * [Better Auth Astro Guide](https://www.better-auth.com/docs/integrations/astro) * [Better Auth Astro Example](https://github.com/better-auth/examples/tree/main/astro-example) * [Better Auth Documentation](https://www.better-auth.com/docs) * [Better Auth GitHub Repository](https://github.com/better-auth/better-auth) ## Clerk [Section titled “Clerk”](#clerk) Clerk is a complete suite of embeddable UIs, flexible APIs, and admin dashboards to authenticate and manage your users. An [official Clerk SDK for Astro](https://clerk.com/docs/references/astro/overview) is available. ### Installation [Section titled “Installation”](#installation-2) Install `@clerk/astro` using the package manager of your choice. * npm ```shell npm install @clerk/astro ``` * pnpm ```shell pnpm add @clerk/astro ``` * Yarn ```shell yarn add @clerk/astro ``` ### Configuration [Section titled “Configuration”](#configuration-2) Follow [Clerk’s own Astro Quickstart guide](https://clerk.com/docs/quickstarts/astro) to set up Clerk integration and middleware in your Astro project. ### Usage [Section titled “Usage”](#usage-2) Clerk provides components that allow you to control the visibility of pages based on your user’s authentication state. Show logged out users a sign in button instead of the content available to users who are logged in: src/pages/index.astro ```astro --- import Layout from 'src/layouts/Base.astro'; import { SignedIn, SignedOut, UserButton, SignInButton } from '@clerk/astro/components'; export const prerender = false; // Not needed in 'server' mode --- ``` Clerk also allows you to protect routes on the server using middleware. Specify which routes are protected, and prompt unauthenticated users to sign in: src/middleware.ts ```ts import { clerkMiddleware, createRouteMatcher } from '@clerk/astro/server'; const isProtectedRoute = createRouteMatcher([ '/dashboard(.*)', '/forum(.*)', ]); export const onRequest = clerkMiddleware((auth, context) => { if (!auth().userId && isProtectedRoute(context.request)) { return auth().redirectToSignIn(); } }); ``` ### Next Steps [Section titled “Next Steps”](#next-steps-2) * Read the [official `@clerk/astro` documentation](https://clerk.com/docs/references/astro/overview) * Start from a template with the [Clerk + Astro Quickstart project](https://github.com/clerk/clerk-astro-quickstart) ## Lucia [Section titled “Lucia”](#lucia) [Lucia](https://lucia-auth.com/) is a resource for implementing session-based authentication in a number of frameworks, including Astro. ### Guides [Section titled “Guides”](#guides) 1. Create a [basic sessions API](https://lucia-auth.com/sessions/basic-api/) with your chosen database. 2. Add [session cookies](https://lucia-auth.com/sessions/cookies/astro) using endpoints and middleware. 3. Implement [GitHub OAuth](https://lucia-auth.com/tutorials/github-oauth/astro) using the APIs you implemented. ### Examples [Section titled “Examples”](#examples) * [GitHub OAuth example in Astro](https://github.com/lucia-auth/example-astro-github-oauth) * [Google OAuth example in Astro](https://github.com/lucia-auth/example-astro-google-oauth) * [Email and password example with 2FA in Astro](https://github.com/lucia-auth/example-astro-email-password-2fa) * [Email and password example with 2FA and WebAuthn in Astro](https://github.com/lucia-auth/example-astro-email-password-webauthn) ## Community Resources [Section titled “Community Resources”](#community-resources) * [Using Microsoft Entra Id EasyAuth with Astro and Azure Static Web App](https://agramont.net/blog/entra-id-easyauth-with-astro/) # E-commerce > An introduction to adding e-commerce options to your Astro site 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 [Section titled “Payment processing overlays”](#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 [Section titled “Lemon Squeezy”](#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 [Section titled “Basic Usage”](#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 ` ``` 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. src/pages/my-product-page.astro ```html Buy Now ``` #### Lemon.js [Section titled “Lemon.js”](#lemonjs) 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/handling-events). Read the [Lemon Squeezy developer getting started guide](https://docs.lemonsqueezy.com/guides/developer-guide) for more information. ### Paddle [Section titled “Paddle”](#paddle) [Paddle](https://www.paddle.com/) is a billing solution for digital products and services. It handles 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 [Section titled “Basic Usage”](#basic-usage-1) 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 ` ``` 2. Turn any element on your page into a Paddle Checkout button by adding the `paddle_button` class: src/pages/my-product-page.astro ```html Buy Now ``` 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: src/pages/my-product-page.astro ```html Buy now ``` #### Paddle.js [Section titled “Paddle.js”](#paddlejs) 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. Read more about [using Paddle.js to build an inline checkout](https://developer.paddle.com/build/checkout/build-branded-inline-checkout). ## Full-featured e-commerce solutions [Section titled “Full-featured e-commerce solutions”](#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 [Section titled “Snipcart”](#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. #### Basic Usage [Section titled “Basic Usage”](#basic-usage-2) 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. For complete instructions, including setting up your Snipcart store, please see [the Snipcart installation documentation](https://docs.snipcart.com/v3/setup/installation). 1. Add the script [as shown in the Snipcart installation instructions](https://docs.snipcart.com/v3/setup/installation) on your page after the `` element. src/pages/my-product-page.astro ```html ``` 2. Customize `window.SnipcartSettings` with any of the [available Snipcart settings](https://docs.snipcart.com/v3/setup/installation#settings) to control the behavior and appearance of your cart. src/pages/my-product-page.astro ```html ``` 3. Add `class="snipcart-add-item"` to any HTML element, such as a ` ``` 4. Add a Snipcart checkout button with the `snipcart-checkout` class to open the cart and allow guests to complete their purchase with a checkout modal. src/pages/my-product-page.astro ```html ``` #### Snipcart JavaScript SDK [Section titled “Snipcart JavaScript SDK”](#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. See the [Snipcart documentation](https://docs.snipcart.com/v3/) for more information about all the options to integrate Snipcart with your Astro Project. #### `astro-snipcart` [Section titled “astro-snipcart”](#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 [Section titled “Community Resources”](#community-resources) * [Hands-On Experience: eCommerce Store with Astro?](https://crystallize.com/blog/building-ecommerce-with-astro) * [Collecting Payments with Stripe using Astro](https://zellwk.com/blog/stripe-astro-recipe/) # Image and video hosting with Astro > How to use a hosted media service to add images and videos to Astro Follow one of our guides to integrate images and videos from a hosted media service. ## Hosted Media Guides [Section titled “Hosted Media Guides”](#hosted-media-guides) * ![](/logos/cloudinary.svg) ### [Cloudinary](/en/guides/media/cloudinary/) * ![](/logos/mux.svg) ### [Mux](/en/guides/media/mux/) ## Why use hosted media? [Section titled “Why use hosted media?”](#why-use-hosted-media) Hosted media helps individuals, teams, and organizations store, manage, optimize, and deliver their image and video assets with dedicated APIs from a central location. This centralization can be useful, particularly when using a single source of truth for your assets between multiple web or mobile properties. This is important if you’re part of an organization that requires multiple teams to use the same assets, or are integrating into other content systems like a PIM (Product Information Manager) to connect your assets to products. Image hosting services can transform and optimize your images, automatically delivering optimized versions for your visitors. These [remote images](/en/guides/images/#remote-images) can be used in Astro’s built-in `` and `