Home

Table of Contents

---

1. Overview
2. Prerequisites
3. Key directories and files
4. Installation
5. Testing
6. Frontend development
7. Further resources

---

Overview

The Droplet Template is a Rails 8 application designed to serve as a starting point for creating third-party integrations (called "droplets") for the Fluid software platform platform. This template provides the basic structure and features for creating and managing a Droplet.

Prerequisites

• Ruby 3.4+ (recommended: 3.4.2)
• Rails 8.0+ (recommended: 8.0.2)
• PostgreSQL 17+
• Node.js 23.8+
• Yarn 4.7+
• Redis 7.0+
• Git

Key directories and files

• app/clients/ - Client libraries for communicating with the main platform

  • fluid_client.rb - Main client for the platform
  • fluid/droplets.rb - Module included in the Fluid client that handles the droplet resource

• app/frontend/ - Frontend assets using React and TypeScript

  • components/ - Reusable React components
  • entrypoints/ - Entry points for each page
  • lib/ - Utility functions and helpers
  • fontawesome.js - Font Awesome configuration

• app/permissions/ - Role-based permission system

  • ability.rb - CanCanCan ability definitions
  • admin_permissions.rb - Admin-specific permissions
  • permission_set.rb - Base class for permission sets

• Configuration Files

  • tailwind.config.js - Tailwind CSS configuration
  • vite.config.js - Vite bundler configuration
  • docker-compose.yml - Docker Compose configuration

Installation

1. Clone the repository

git clone git@github.com:fluid-commerce/droplet-template.git
cd droplet-template

2. Install the dependencies

bundle install
yarn install

3. Set up the database

bin/rails db:prepare

4. Start the development server using the included development scripts

bin/dev

This will start both the Rails server and the Vite development server for frontend assets.

Testing

The template includes a comprehensive test suite using Minitest for Ruby code and Jest for JavaScript/TypeScript components.

Run the Ruby tests with:

rails test

The test suite includes:

Model tests in test/models/
Controller tests in test/controllers/
Client tests in test/clients/
Permission tests in test/permissions/

Run the JavaScript tests with:*

yarn test

JavaScript tests are adjacent to the files they are testing. Frontend tests are configured with Jest as specified in jest.config.json.

Frontend development

The template uses modern frontend tools for a responsive and interactive UI:

Tailwind CSS
Tailwind CSS 4.0 is configured and ready to use for styling. The configuration can be found in tailwind.config.js.

React with TypeScript
React components are written in TypeScript for type safety and better developer experience. The template includes:

TypeScript configuration in tsconfig.json and tsconfig.node.json
React components in app/frontend/components/
React entrypoints in app/frontend/entrypoints/

Vite for Asset Bundling
Vite is used for fast frontend development and efficient bundling:

Configuration in vite.config.js
Integration with Rails via the vite-rails gem

Font Awesome
Font Awesome 6.7.2 is included for icons, configured in app/frontend/fontawesome.js.

Further resources

Rails 8 Documentation
Tailwind CSS Documentation
TypeScript Documentation
React Documentation
Vite Documentation