Fluid Droplet Management System

A comprehensive Fluid droplet template that provides complete droplet lifecycle management, order processing, product management, and webhook handling capabilities.

🚀 What This Droplet Does

This is a full-featured Fluid droplet that provides:

• Complete Droplet Management - Create, update, and manage Fluid droplets
• Order Processing System - Handle orders with status tracking and management
• Product Management - Full CRUD operations for products with inventory tracking
• Webhook Integration - Secure webhook handling for real-time data synchronization
• Company Management - Multi-tenant support with company-specific data isolation
• DIT Token Authentication - Automatic company authentication using Fluid DIT tokens
• Dashboard Interface - Modern React frontend with comprehensive management tools

🔑 Authentication System

This droplet uses DIT (Droplet Installation Token) authentication, which means:

• No Manual API Keys Required - Companies don't need to provide their own API keys
• Automatic Authentication - When a company installs your droplet, Fluid automatically provides a DIT token
• Secure by Default - DIT tokens are scoped to the specific installation and company
• Zero Configuration - Companies can start using your droplet immediately after installation

How DIT Tokens Work

1. Company installs your droplet → Fluid generates a unique DIT token
2. DIT token is sent via webhook → Your backend receives and stores it
3. API calls use DIT token → All Fluid API calls are authenticated automatically
4. No manual setup required → Companies don't need to configure anything

Project Structure

• frontend/ - Simple React app that shows company info
• backend/ - Node.js API with webhook handling
• database/ - PostgreSQL with Prisma for company data
• scripts/ - Tools to create and update your droplet

Quick Start

1. Install dependencies:

npm install
cd frontend && npm install
cd ../backend && npm install
cd ../database && npm install

2. Set up database:

# Database is already configured for local development
npm run prisma:push

3. Start development:

npm run dev

This starts:

• Frontend: http://localhost:5173
• Backend: http://localhost:3001

Creating Your Droplet

1. Deploy to production (Render, Vercel, etc.)
2. Get your Fluid API key from your Fluid account
3. Create the droplet:

FLUID_API_KEY=your_api_key_here \
EMBED_URL=https://your-frontend-url.com/ \
DROPLET_NAME="My Simple Droplet" \
node scripts/create-droplet.js

How It Works

1. Company installs droplet → Fluid sends webhook to your backend
2. Backend stores company info (name, logo) in database
3. Frontend loads → shows company name and logo in clean header
4. That's it! Simple and clean.

Available Scripts

• npm run dev - Start both frontend and backend
• npm run prisma:generate - Generate Prisma client
• npm run prisma:push - Push schema to database
• npm run prisma:studio - Open Prisma Studio

Customizing

This template is intentionally simple. To add features:

1. Add new database models in database/prisma/schema.prisma
2. Add API endpoints in backend/src/index.ts
3. Add UI components in frontend/src/components/

The code is clean and organized - easy to understand and modify!

🚀 How to Build Your Own Fluid Droplet

Complete guide to create a Fluid droplet that connects different apps together
No coding experience needed - anyone can follow this guide!

🎯 What You're Building

By the end of this guide, you'll have created a Fluid droplet - a small app that connects different services together. Think of it like a bridge between apps.

For example: Your droplet could automatically send new customers to an email marketing tool, or sync orders between different stores.

---

📋 What You Need to Get Started

Before we begin, you need these accounts:

• ✅ GitHub account - Where your code lives online
• ✅ Render account - Where your app runs on the internet
• ✅ Fluid account - Where your droplet gets listed for people to use
• ✅ Cursor IDE - Where your droplet will be vibed/coded & built
• ✅ About 45 minutes to complete setup

---

Step 1: Create Your GitHub Account

If you don't have GitHub yet:

1. Go to github.com
2. Click "Sign up" in the top right corner
3. Fill in your information:
   • Pick a username (something you'll remember)
   • Your email address
   • A password
4. Check your email and click the verification link
5. Skip the questions about your interests - you can leave them blank

If you already have GitHub:

Great! Move to Step 2.

---

Step 2: Get Your Own Copy of the Template

You need to make your own copy of the Fluid droplet template. Here are two ways to do it:

Option A: Clone with Git (Recommended for Cursor)

This is the best way if you plan to use Cursor IDE for development:

1. Copy the repository URL: https://github.com/fluid-commerce/Droplet-Template-React-.git
2. Open your terminal/command prompt
3. Navigate to where you want the project:

   cd Desktop  # or wherever you want it

4. Clone the repository:

   git clone https://github.com/fluid-commerce/Droplet-Template-React-.git

5. Enter the project folder:

   cd Droplet-Template-React-

Option B: Download as ZIP

If you prefer to download directly:

1. Go to the template repository on GitHub
2. Click the green "Code" button
3. Click "Download ZIP"
4. Extract the ZIP file to your Desktop or preferred location
5. The folder will be named Droplet-Template-React- (you can rename it if you prefer)

Step 2.5: Open in Cursor IDE

Now let's get your template into Cursor for that sweet AI-powered development experience:

Install Cursor (if you haven't already):

1. Go to cursor.sh
2. Download Cursor for your operating system
3. Install it like any other app

Open Your Project in Cursor:

Method 1 - From Cursor:

1. Open Cursor IDE
2. Click "Open Folder" or use Cmd+O (Mac) / Ctrl+O (Windows)
3. Navigate to your Droplet-Template-React- folder
4. Click "Open"

Method 2 - From Terminal (if you cloned):

1. Make sure you're in the project folder:

   cd Droplet-Template-React-

2. Open in Cursor:

   cursor .

Method 3 - Drag and Drop:

1. Open Cursor IDE
2. Drag your Droplet-Template-React- folder directly into the Cursor window

What You'll See in Cursor:

Once opened, you'll see the complete project structure:

• frontend/ - React app with TypeScript
• backend/ - Node.js API server
• database/ - PostgreSQL migrations
• scripts/ - Automation helpers

🎉 You're now ready to start vibing with AI-powered development!

Cursor will understand your entire codebase and can help you:

• Add new integrations (just ask: "Add Shopify integration")
• Customize the UI ("Make the dashboard more modern")
• Debug issues ("Why is my webhook not working?")
• Add features ("Add bulk data import functionality")

Step 2.6: Create Your Own GitHub Repository

Since you cloned the template, you need to create your own repository to save your customizations:

Create a New Repository on GitHub:

1. Go to github.com and sign in
2. Click the "+" icon in the top right corner
3. Click "New repository"
4. Name your repository (e.g., my-fluid-droplet or shopify-email-sync)
5. Make it Public (required for free Render deployment)
6. Don't initialize with README, .gitignore, or license (you already have these)
7. Click "Create repository"

Connect Your Local Code to Your New Repository:

After creating the repository, GitHub will show you commands. Follow these steps:

1. In your terminal/command prompt, make sure you're in your project folder:

   cd Droplet-Template-React-

2. Remove the connection to the original template:

   git remote remove origin

3. Connect to your new repository (replace YOUR_USERNAME and YOUR_REPO_NAME):

   git remote add origin https://github.com/YOUR_USERNAME/YOUR_REPO_NAME.git

4. Push your code to your repository:

   git branch -M main
   git push -u origin main

After Making Changes in Cursor:

Whenever you customize your droplet in Cursor, you need to save and push your changes:

1. Save your files in Cursor (Cmd+S or Ctrl+S)

2. In terminal, add your changes:

   git add .

3. Commit your changes with a message:

   git commit -m "Add Shopify integration and custom styling"

4. Push to GitHub:

   git push

🚀 Important: Render automatically deploys when you push to GitHub! Your changes will be live in 2-3 minutes.

---

Step 3: Create Your Render Account

Render is where your app will live on the internet.

1. Go to render.com
2. Click "Get Started for Free"
3. Choose "Sign up with GitHub" - this connects your accounts
4. Click "Authorize" when GitHub asks for permission
5. Fill out your profile:
   • Pick a username
   • Choose the Free plan (perfect for starting)
   • Verify your email if asked

---

Step 4: Deploy Your App to Render

This is where the magic happens! Render will automatically create everything you need.

What is a Blueprint?

A Blueprint is like a recipe that tells Render exactly how to build your app. Your template includes this recipe, so Render knows what to do.

Understanding the render.yaml File

Your template includes a special file called render.yaml that acts as the blueprint. Here's what it does:

The render.yaml file tells Render to create:

• Frontend Service - Hosts your React app (Static Site)
• Backend Service - Runs your Node.js API server (Web Service)
• PostgreSQL Database - Stores all your data securely

How Environment Variables Work: The render.yaml file defines which environment variables your app needs, but it doesn't include the actual secret values (for security). You'll add the real values manually in Render's dashboard.

Template includes these pre-configured variables:

• DATABASE_URL - Automatically set by Render (connects to your database)
• FLUID_API_KEY - You'll add your Fluid API key
• FLUID_WEBHOOK_SECRET - You'll add your webhook secret
• JWT_SECRET - You'll generate this for security
• ENCRYPTION_KEY - You'll generate this to encrypt data
• NODE_ENV - Set to "production"
• PORT - Set to 3001 for the backend

Adding New Variables When You Add Features

When you add integrations (like Shopify, Stripe, etc.), you'll need to:

1. Add to render.yaml - So Render knows your app needs them
2. Add to Render dashboard - So your app can access the real values
3. Use in your code - So your integration can connect

Example: Adding Shopify Integration

If you ask Cursor to "Add Shopify integration," it will help you:

Step 1: Update render.yaml

services:
  - type: web
    name: my-droplet-backend
    env: node
    buildCommand: cd backend && npm install && npm run build
    startCommand: cd backend && npm start
    envVars:
      # ... existing variables ...
      - key: SHOPIFY_API_KEY
        sync: false
      - key: SHOPIFY_SECRET_KEY  
        sync: false
      - key: SHOPIFY_WEBHOOK_SECRET
        sync: false

Step 2: Add Values in Render Dashboard

• Go to your Backend service → Environment tab
• Add SHOPIFY_API_KEY with your actual Shopify API key
• Add SHOPIFY_SECRET_KEY with your Shopify secret
• Add SHOPIFY_WEBHOOK_SECRET with your webhook secret

Step 3: Use in Your Code Cursor will automatically generate code that uses these variables:

const shopifyClient = new ShopifyApi({
  apiKey: process.env.SHOPIFY_API_KEY,
  secretKey: process.env.SHOPIFY_SECRET_KEY,
  webhookSecret: process.env.SHOPIFY_WEBHOOK_SECRET
});

Deploy Your App:

1. In Render, click "New +" (top right corner)
2. Click "Blueprint" from the menu
3. Connect your GitHub:
   • If not connected, click "Connect GitHub account"
   • Select your repository (the one your droplet lives in)
   • Choose the main branch
4. Review what will be created:
   • You'll see 3 services: Frontend, Backend, and Database
   • This is normal and exactly what you want
5. Click "Apply" to start building

What Happens Next:

• Render reads your template
• Creates 3 separate services (like 3 different computers working together)
• Builds your app and makes it live on the internet
• Sets up a database to store information
• Gives you web addresses where people can access your app

This takes 5-10 minutes. You can grab a coffee while it builds!

---

Step 5: Create Your Fluid Account

Fluid is where people will find and install your droplet.

1. Go to fluid.app
2. Click "Sign Up" or "Get Started"
3. Enter your email and password
4. Check your email and click the verification link

---

Step 6: Get Your API Keys

API keys are like passwords that let your app talk to other services.

Get Your Fluid API Key:

1. Log into your Fluid account
2. Look for "Developer" or "API" section in the menu
3. Find "API Key" or "API Keys"
4. Create a new API key:
   • Name it something like "My Droplet Integration"
   • Copy the key (it starts with PT-)
   • ⚠️ Save this somewhere safe - you'll need it soon!

Create a Webhook Secret:

A webhook secret is like a password that proves messages are really from Fluid.

Easy way to create one:

1. Go to generate-secret.vercel.app/32
2. Copy the generated string
3. Save it somewhere safe

---

Step 7: Set Up Your App Settings

Your app needs to know some secret information to work. These are called "environment variables."

Remember: The render.yaml file already told Render which variables your app needs, but it didn't include the actual secret values. Now you'll add the real values so your app can use them.

How to Add Settings in Render:

1. In your Render dashboard, find your Backend service
2. Click on it, then click "Environment" tab
3. Add these settings one by one:

Required Settings:

FLUID_API_KEY

• Key: FLUID_API_KEY
• Value: PT-your-actual-api-key-here (the one you copied from Fluid)

FLUID_WEBHOOK_SECRET

• Key: FLUID_WEBHOOK_SECRET
• Value: your-32-character-secret-here (the one you generated)

JWT_SECRET

• Key: JWT_SECRET
• Value: Go to generate-secret.vercel.app/64 and copy the result

ENCRYPTION_KEY

• Key: ENCRYPTION_KEY
• Value: Go to generate-secret.vercel.app/32 and copy the result

NODE_ENV

• Key: NODE_ENV
• Value: production

PORT

• Key: PORT
• Value: 3001

How to Add Each Setting:

1. Click "Add Environment Variable"
2. Type the Key (like FLUID_API_KEY)
3. Type the Value (like your actual API key)
4. Click "Save Changes"
5. Repeat for each setting

---

Step 8: Get Your App URLs

After your app finishes building, you'll get web addresses where it lives.

Find Your URLs:

1. In Render dashboard, look at your services
2. Find your Frontend service - click on it
3. Copy the URL (something like https://your-app-frontend.onrender.com)
4. Find your Backend service - click on it
5. Copy the URL (something like https://your-app-backend.onrender.com)

Add URL Settings:

Go back to your Backend service environment variables and add:

FRONTEND_URL

• Key: FRONTEND_URL
• Value: Your frontend URL

WEBHOOK_BASE_URL

• Key: WEBHOOK_BASE_URL
• Value: Your backend URL

Add Frontend Settings:

1. Go to your Frontend service in Render
2. Click "Environment" tab
3. Add this setting:

VITE_API_BASE_URL

• Key: VITE_API_BASE_URL
• Value: Your backend URL

---

Step 9: Test Your App

Let's make sure everything is working!

Test Your Backend:

1. Open a new browser tab
2. Go to your backend URL + /health
   • Example: https://your-backend.onrender.com/health
3. You should see: {"status":"ok","timestamp":"..."}

Test Your Frontend:

1. Go to your frontend URL
2. You should see your droplet interface
3. It should load without any error messages

If something doesn't work, check the logs in Render dashboard.

---

Step 10: Register Your Droplet with Fluid

Now you need to tell Fluid about your droplet so people can find it.

Create Your Droplet:

1. Open a text editor (like Notepad or TextEdit)
2. Copy this command and replace the parts in CAPS:

curl -X POST https://api.fluid.app/api/droplets \
  -H "Authorization: Bearer YOUR_FLUID_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "droplet": {
      "name": "Your Droplet Name",
      "embed_url": "YOUR_FRONTEND_URL_HERE/",
      "active": true,
      "settings": {
        "marketplace_page": {
          "title": "Your Droplet Name",
          "summary": "Description of what your droplet does",
          "logo_url": "https://your-logo-url.com/logo.png"
        },
        "details_page": {
          "title": "Your Droplet Name", 
          "summary": "Description of what your droplet does",
          "logo_url": "https://your-logo-url.com/logo.png"
        }
      }
    }
  }'

3. Replace these parts:

   • YOUR_FLUID_API_KEY_HERE with your actual API key
   • YOUR_FRONTEND_URL_HERE with your actual frontend URL
   • Your Droplet Name with what you want to call your droplet
   • Description of what your droplet does with a description

4. Save the file as create-droplet.txt

Run the Command:

If you're on Windows:

1. Open Command Prompt (search for "cmd" in Start menu)
2. Copy and paste your command
3. Press Enter

If you're on Mac:

1. Open Terminal (search for "Terminal" in Spotlight)
2. Copy and paste your command
3. Press Enter

Get Your Droplet ID:

After running the command, you'll get a response that includes a uuid. It looks like:

{
  "droplet": {
    "uuid": "drp_abc123xyz789",
    "name": "Your Droplet Name"
  }
}

Copy that UUID - you'll need it next!

---

Step 11: Add Your Droplet ID to Render

1. Go back to your Backend service in Render
2. Click "Environment" tab
3. Add this setting:

DROPLET_ID

• Key: DROPLET_ID
• Value: The UUID you copied (starts with drp_)

4. Click "Manual Deploy" → "Deploy latest commit" to restart your app

---

Step 12: Test Everything Together

Now let's test your complete droplet!

Test the Full Flow:

1. Go to your Fluid account
2. Look for your droplet in the marketplace or droplets section
3. Click "Install" on your droplet
4. You should see:
   • Your droplet loads in a window
   • It recognizes your company automatically
   • Shows a success message
   • Displays your company name

If Something Doesn't Work:

1. Check Render logs:

   • Go to Backend service → Logs tab
   • Look for red error messages

2. Verify your settings:

   • Make sure all environment variables are set correctly
   • Check that URLs match your actual deployment

3. Test your endpoints:

   • Backend health: https://your-backend.onrender.com/health
   • Webhook health: https://your-backend.onrender.com/api/webhook/health

---

🎉 Congratulations!

You now have a live Fluid droplet that:

• ✅ People can install from the Fluid marketplace
• ✅ Automatically configures when someone clicks "Install"
• ✅ Shows company information right away
• ✅ Handles webhooks and data synchronization
• ✅ Stores data securely in a database
• ✅ Scales automatically as more people use it

---

📝 How to Customize Your Droplet

Update Your Droplet's Name and Description:

You can change how your droplet appears to users by updating it in Fluid.

Easy Way - Use the Scripts:

Your template includes helpful scripts to update your droplet.

Update Your Description:

FLUID_API_KEY=PT-your-api-key-here
DROPLET_ID=drp_your-droplet-uuid
DROPLET_NAME="My Awesome Integration"
DROPLET_DESCRIPTION="🚀 Connect your Shopify store with email marketing - sync customers, orders, and more!"
node scripts/update-droplet.js

Update Your Logo:

1. Upload your logo to any image hosting service (like Imgur)
2. Get the image URL
3. Run this command:

FLUID_API_KEY=PT-your-api-key-here
DROPLET_ID=drp_your-droplet-uuid
LOGO_URL=https://your-logo-url.com/logo.png
node scripts/update-droplet.js

Make Your Description Better:

• Use emojis to make it more interesting
• Focus on benefits - what does it do for the user?
• Keep it short but informative
• Include your target audience

Example of a good description: "🚀 Automatically sync your Shopify store with email marketing platforms. 📧 Get instant customer data, 📊 track order events, and 🎯 create targeted campaigns. Perfect for growing businesses!"

---

🔒 Your App is Secure

Your droplet template includes built-in security features:

• Data is encrypted - All sensitive information is protected
• Companies are isolated - Each company only sees their own data
• Webhooks are verified - Only real messages from Fluid are processed
• Rate limiting - Prevents anyone from overwhelming your system
• Input validation - All data is checked before processing

You don't need to do anything special - it's all built in!

---

🗄️ How Your Database Works

Your app automatically creates and manages a database to store information:

• Company configurations - Settings for each company that installs your droplet
• Activity logs - Records of everything that happens
• Webhook events - Messages from Fluid platform
• Custom data - Information from connected services

The database is automatically backed up and scales with your app.

---

🚨 If Something Goes Wrong

Common Problems and Solutions:

"Service won't start"

• Check that all environment variables are set correctly
• Look at Render logs for specific error messages

"Database connection failed"

• The database URL is set automatically by Render
• Make sure your database service shows "Available" status

"Droplet not found in Fluid"

• Check that your DROPLET_ID matches the UUID from Fluid
• Verify your FLUID_API_KEY is correct and has proper permissions

"Frontend shows errors"

• Make sure VITE_API_BASE_URL points to your backend
• Check that your backend service shows "Live" status

Getting Help:

1. Render Support: render.com/support
2. Fluid Documentation: docs.fluid.app
3. Ask the person who gave you this guide

---

🔧 Adding New Features & Integrations

Now that your droplet is live, here's how to add new features and third-party integrations:

The Three-Step Process for Any New Integration:

Every time you add a new service (Shopify, Stripe, Mailchimp, etc.), follow these steps:

Step 1: Ask Cursor to Add the Integration

Simply ask Cursor in natural language:

• "Add Shopify integration with product sync"
• "Add Stripe payment processing"
• "Add Mailchimp email automation"
• "Add Google Sheets data export"

Cursor will generate all the necessary code and tell you what environment variables you need.

Step 2: Update Your render.yaml File

When Cursor adds the integration, it may tell you to add new environment variables to render.yaml.

Example for Shopify:

envVars:
  # ... existing variables ...
  - key: SHOPIFY_API_KEY
    sync: false
  - key: SHOPIFY_SECRET_KEY
    sync: false
  - key: SHOPIFY_WEBHOOK_SECRET
    sync: false
  - key: SHOPIFY_APP_URL
    sync: false

Step 3: Add the Real Values in Render

1. Go to your Backend service in Render dashboard
2. Click "Environment" tab
3. Add each new variable with the real API keys/secrets
4. Click "Manual Deploy" to restart with new variables

Step 4: Push Your Code

git add .
git commit -m "Add Shopify integration with product sync"
git push

Render will automatically deploy your changes in 2-3 minutes!

Common Integrations & Their Variables:

Shopify Integration:

• SHOPIFY_API_KEY - Your Shopify app's API key
• SHOPIFY_SECRET_KEY - Your Shopify app's secret
• SHOPIFY_WEBHOOK_SECRET - For webhook verification
• SHOPIFY_APP_URL - Your app's URL in Shopify

Stripe Integration:

• STRIPE_SECRET_KEY - Your Stripe secret key
• STRIPE_WEBHOOK_SECRET - For webhook verification
• STRIPE_PUBLISHABLE_KEY - For frontend payments

Email Services (Mailchimp, SendGrid, etc.):

• MAILCHIMP_API_KEY - Your Mailchimp API key
• SENDGRID_API_KEY - Your SendGrid API key
• EMAIL_FROM_ADDRESS - Default sender email

Social Media (Facebook, Instagram, etc.):

• FACEBOOK_APP_ID - Your Facebook app ID
• FACEBOOK_APP_SECRET - Your Facebook app secret
• INSTAGRAM_ACCESS_TOKEN - Instagram API token

Pro Tips:

1. Always test locally first - Use a .env file for development
2. Use descriptive commit messages - Makes it easy to track changes
3. Check Render logs after deployment to ensure everything works
4. Keep secrets safe - Never commit API keys to GitHub
5. Document your integrations - Add comments explaining what each integration does

---

📚 What's Next?

Monitor Your Droplet:

1. Check Render logs regularly for any issues
2. Watch database usage in Render dashboard
3. Set up alerts for service downtime
4. Track user installations in your Fluid account

Scale When You Need To:

• Free tier supports up to 750 hours/month
• Paid plans start at $7/month for always-on services
• Database plans start at $7/month for production use

Customize Further:

1. Update the name and description in your Fluid droplet settings
2. Add your company logo
3. Customize the interface to match your brand
4. Add specific API integrations (Shopify, Stripe, etc.)

---

🎯 You Did It!

You've successfully created a professional Fluid droplet that:

• Connects different services together
• Handles real-time data synchronization
• Processes webhooks securely
• Stores data safely in a database
• Scales automatically as you grow

Your droplet is now live and ready for people to use!

---

🚀 Ready to Connect the World?

You've built a bridge between apps that businesses can use to automate their workflows.

🎯 Your droplet is live and ready to help companies work more efficiently!

Made with ❤️ for the Fluid community