flomodev

v0.1.7

Published

3 months ago

Visual animation authoring for React - zero runtime overhead

0High
0Medium
0Low

thisiskuldeep

react nextjs animation devtools ui visual css motion transitions

Flomo

Visual animation authoring for React applications. Create animations visually in dev mode, export to CSS, and ship with zero runtime overhead.

Overview

Flomo provides a visual editor overlay for authoring UI animations during development. Animations are saved to CSS files in your project and compiled into production builds automatically.

Core Principle: Only CSS animations ship to production - no runtime library overhead.

Key Benefits

Zero Runtime Cost - Animations compile to pure CSS, no JavaScript in production
Visual Editor - Point-and-click interface for creating animations
AI-Powered - Generate animations with natural language prompts
Framework Agnostic - Works with Next.js and vanilla React
SSR Safe - Compatible with server-side rendering
TypeScript First - Full type definitions included

Installation

Flomo is published to npm and works with all major package managers:

# npm
npm install flomodev

# pnpm
pnpm add flomodev

# yarn
yarn add flomodev

# bun
bun add flomodev

Requirements

React 18.0.0 or higher
React DOM 18.0.0 or higher

Getting Your API Key

Flomo's AI-powered animation generation requires an API key from flomo.dev.

Why You Need an API Key

AI Animation Generation: Create animations using natural language prompts powered by Flomo's AI backend
Credit System: Track and manage your animation generation credits
Free Tier Available: Get started with free credits to try out AI animations

How to Get Your API Key

Sign up at flomo.dev
- Create a free account
- Get instant access to free credits
Copy your API key from the dashboard
- Navigate to your account settings
- Find your API key under "Developer Settings"

Configure in your project

npx flomodev apikey YOUR_API_KEY_HERE

Or manually add to .env.local:

NEXT_PUBLIC_FLOMO_API_KEY=your_api_key_here

Note: Manual animation editing works without an API key. You only need the API key for AI-powered animation generation.

Quick Start

Next.js Setup

1. Initialize Flomo (Recommended)

npx flomodev init

This command creates the CSS file, API route for saving animations, and adds the necessary imports to your layout.

2. Add FlomoProvider to your layout

// app/layout.tsx
import { FlomoProvider } from 'flomodev'
import 'flomodev/dist/index.css'
import './styles/flomo-animations.css'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <FlomoProvider>
          {children}
        </FlomoProvider>
      </body>
    </html>
  )
}

3. Start development

npm run dev

The Flomo overlay appears at the bottom of your page in development mode.

Vanilla React Setup

1. Add FlomoProvider to your app

// src/App.tsx
import { FlomoProvider } from 'flomodev'
import 'flomodev/dist/index.css'

function App() {
  return (
    <FlomoProvider devMode={process.env.NODE_ENV === 'development'}>
      {/* Your app content */}
    </FlomoProvider>
  )
}

export default App

2. Import animations CSS in production

Create a file src/flomo-animations.css with your exported animations and import it in your app.

Features

Visual Animation Editor

Point-and-click selection - Click any element to animate it
Live preview - See animations in real-time as you adjust
Instant feedback - Changes apply immediately

AI-Powered Generation

Natural language prompts - Describe the animation you want
Smart detection - AI analyzes element roles and layout
Stagger support - Animate children, words, or letters

Animation Controls

Duration - 0-5000ms
Delay - 0-5000ms
Easing - Multiple easing functions
Transform - Translate, scale, rotate
Opacity - Fade in/out
Stagger - Sequential animations for groups

Usage Guide

Manual Animation Mode

Enable Select Mode
- Click "Select" in the bottom bar
- Click any element on the page
Configure Animation
- Choose trigger: onMount, onInView, or onHover
- Select animation effect (fade, slide, scale, etc.)
- Adjust duration, delay, and easing
- Set from/to states for transforms
Preview and Apply
- Click "Preview" to test the animation
- Click "Apply" to save
Export
- Click "Save" to persist animations to CSS file

AI-Powered Generation

Enter Prompt
- Describe the animation: "fade in from left with stagger"
- Or leave empty for automatic generation
Generate
- Click "Generate"
- Animations are generated in real-time
Apply
- Preview the results
- Click "Apply" to add animations

AI Prompt Examples

"Fade in from bottom with stagger"
"Scale up on hover"
"Slide in from left, one by one"
"Stagger children with 100ms delay"
"Word by word reveal"
"Letter by letter animation"
"Bounce in from top"
"Smooth fade with scale"

CLI Commands

All commands should be run from your project root:

# Initialize Flomo in your project (Next.js)
npx flomodev init

# Show the dev overlay
npx flomodev show

# Hide the dev overlay
npx flomodev hide

# Clear all animations
npx flomodev clearall

# Show help
npx flomodev help

| Command | Description | |---------|-------------| | init | Creates CSS file, API route, and adds imports (Next.js only) | | show | Enables the development overlay | | hide | Disables the overlay (animations are preserved) | | clearall | Resets all animations and localStorage | | help | Shows available commands |

Animation Properties

Transform Properties

| Property | Range | Description | |----------|-------|-------------| | translateX | -1000px to 1000px | Horizontal movement | | translateY | -1000px to 1000px | Vertical movement | | scale | 0 to 2 | Size scaling | | rotate | -360deg to 360deg | Rotation | | opacity | 0 to 1 | Transparency |

Timing Properties

| Property | Range | Default | Description | |----------|-------|---------|-------------| | duration | 0-5000ms | 400ms | Animation length | | delay | 0-5000ms | 0ms | Start delay | | stagger | 0-500ms | 0ms | Delay between children |

Easing Functions

ease-out, ease-in, ease-in-out, linear, ease, smooth

Animation Triggers

| Trigger | Description | Use Case | |---------|-------------|----------| | onMount | Animates immediately when component mounts | Page load animations | | onInView | Animates when element enters viewport | Scroll animations | | onHover | Animates on mouse hover | Interactive elements |

Viewport Threshold (for `onInView`)

Configure how much of the element must be visible before the animation triggers:

10% - Triggers early
25% - Default, balanced
50% - Half visible
75% - Mostly visible
100% - Fully visible

API Reference

Components

FlomoProvider

Wrap your application with FlomoProvider to enable animations:

import { FlomoProvider } from 'flomodev'

<FlomoProvider devMode={true}>
  {children}
</FlomoProvider>

Props:

| Prop | Type | Default | Description | |------|------|---------|-------------| | children | ReactNode | Required | App content | | devMode | boolean | Auto-detected | Enable overlay |

Hooks

useFlomoRef

Apply animations to a specific element:

import { useFlomoRef } from 'flomodev'

function MyComponent() {
  const ref = useFlomoRef('my-element-id')
  return <div ref={ref}>Animated content</div>
}

Troubleshooting

Overlay not appearing

Ensure FlomoProvider wraps your app
Check that you're in development mode
Verify flomodev/dist/index.css is imported
Try running npx flomodev show

Animations not saving

For Next.js: Ensure animations API route was created during npx flomodev init
Check browser console for errors
Try running npx flomodev init again

Animations not playing in production

Verify animations CSS file is imported
Check that file contains generated animations
Ensure elements have data-flomo-id attributes

CLI commands not working

Ensure you're in the project root directory
Run npx flomodev help to verify installation

AI generation fails

No API key configured: See Getting Your API Key section
Invalid API key: Verify your key at flomo.dev
Network issues: Check browser console for errors
Insufficient credits: Check your credit balance at flomo.dev

Known Issues

Stagger and blur effects on text with inner spans

When a text element contains inner <span> elements, stagger and blur effects may not work as expected. This is a known limitation that will be fixed in a future version. Workaround: Remove inner spans or use other animation effects temporarily.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Flomo

Table of Contents

Overview

Key Benefits

Installation

Requirements

Getting Your API Key

Why You Need an API Key

How to Get Your API Key

Quick Start

Next.js Setup

Vanilla React Setup

Features

Visual Animation Editor

AI-Powered Generation

Animation Controls

Usage Guide

Manual Animation Mode

AI-Powered Generation

AI Prompt Examples

CLI Commands

Animation Properties

Transform Properties

Timing Properties

Easing Functions

Animation Triggers

Viewport Threshold (for onInView)

API Reference

Components

FlomoProvider

Hooks

useFlomoRef

Troubleshooting

Overlay not appearing

Animations not saving

Animations not playing in production

CLI commands not working

AI generation fails

Known Issues

Viewport Threshold (for `onInView`)