> ## Documentation Index
> Fetch the complete documentation index at: https://utilsio.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Templates Overview

> A quick guide to using utilsio templates - pre-built application starters with subscriptions already integrated and ready to deploy.

<Tip>
  Instead of setting up everything from scratch, you can clone a template and have a working, production-ready, officially supported subscription system immediately!
</Tip>

## Template vs. SDK vs. API

**When to use what?**

| Approach       | Best For                     | Setup Time   | Flexibility |
| -------------- | ---------------------------- | ------------ | ----------- |
| **Template**   | New projects, MVPs, learning | 5-10 minutes | Medium      |
| **SDK**        | Existing apps, custom UI     | 15 minutes   | High        |
| **Direct API** | Non-JS apps, full control    | 30+ minutes  | Maximum     |

**Recommendation:**

* Starting fresh? Use a [**template**](/guides)
* Have an existing app? Use the [**SDK**](/sdks)
* Using a different language? Use the [**API**](/api-reference)

## Why Use Templates?

It's up to you to choose to use templates or not, but it is advised that you do because it provides integration out-of-the-box, while keeping everything minimal so you can customize it exactly to your needs without redundancies.

<CardGroup cols={2}>
  <Card title="Instant Setup" icon="bolt">
    Clone and set up a working subscription app right now
  </Card>

  <Card title="Best Practices" icon="star">
    Security, error handling, and UX patterns already implemented
  </Card>

  <Card title="Production Ready" icon="check-circle">
    Tested patterns used in real applications, ready for deployment
  </Card>

  <Card title="Officially Supported" icon="book">
    Templates are updated regularly, ensuring that everything just works
  </Card>
</CardGroup>

## Using AI Agents

Use this prompt with your AI coding assistant to integrate utilsio:

```
You are helping me integrate utilsio, a crypto-native subscription system, into my application.

Documentation: https://utilsio.dev/docs
- Installation guide: https://utilsio.dev/docs/install.md
- Full reference: https://utilsio.dev/docs/llms-full.txt
- Quick reference: https://utilsio.dev/docs/llms.txt

Key concepts:
- HMAC-SHA256 request signing (secrets never leave server)
- Client: @utilsio/react with UtilsioProvider + useUtilsio hook
- Server: Server actions using deriveAppHashHex + signRequest
- Safari support: /api/signature-callback endpoint for browsers blocking third-party cookies
- Crypto payments via Superfluid streaming (USDT token)

Decision tree - YOU MUST ANALYZE THE CODEBASE FIRST:
1. Examine the project structure (check for package.json, src/, components/, etc.)
2. Look at key files to assess if this is a new/empty project or existing codebase
3. If codebase appears newly created/minimal, ASK ME: "This looks like a new project. Can I reset the codebase entirely and use the utilsio template for fastest setup?"
   - If YES: Clone template from https://github.com/utilsio/templates (see install.md)
   - If NO: Proceed with manual SDK integration
4. If codebase is clearly mid-development with existing features: Use manual SDK integration

Manual integration:
- Install @utilsio/react package
- Create server action for signing (CRITICAL for security)
- Create /api/signature-callback endpoint for Safari support
- Wrap app with UtilsioProvider
- Never expose UTILSIO_APP_SECRET or UTILSIO_APP_SALT to client

Task: <DESCRIBE WHAT YOU WANT TO BUILD OR INTEGRATE>

My setup:
- Framework: <YOUR FRAMEWORK, e.g., Next.js 15 App Router>
- Package manager: <bun/npm/pnpm/yarn>
- Additional context: <ANY OTHER RELEVANT INFO>
```

## Available Templates

### Next.js Template

Our flagship template built with Next.js 16, TypeScript, and the App Router.

**Tech stack:**

* Next.js 16 (App Router)
* TypeScript
* Tailwind CSS
* utilsio React SDK

**What's included:**

* Complete subscription flow (subscribe, manage, cancel)
* User info and current subscription data fetch and display
* Secure basic signing endpoint with HMAC-SHA256
* Success and cancellation pages
* Environment variable configuration
* Type-safe components and hooks

[View Next.js Template →](/guides/nextjs/quickstart)

**GitHub Repository:** [utilsio/templates/nextjs](https://github.com/utilsio/templates/tree/main/nextjs)

## Learning from Templates

Templates are excellent learning resources:

**Study the code to understand:**

* How to structure a subscription app
* Security best practices for API keys
* User flow design for subscriptions
* Loading state management
* ...

<Tip>
  Even if you're building from scratch, clone a template to see how all the pieces fit together. You can provide the template for your AI coding agent as an example to build your app too!
</Tip>

## Resources

<CardGroup cols={2}>
  <Card title="SDKs Overview" icon="code" href="/sdks">
    Explore all available SDKs for different frameworks
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference">
    Dive into the REST API for custom integrations
  </Card>
</CardGroup>