Betterflow Contributor Guide: Setup and Code Style

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/betterspacx/app/llms.txt

Use this file to discover all available pages before exploring further.

​

Prerequisites

​

Local Setup

git clone https://github.com/konlyzx/betterflow.git
cd betterflow

pnpm install

cp .env.example .env.local

# Site
NEXT_PUBLIC_SITE_URL=http://localhost:3000

# Cloudflare R2 (asset storage — optional for local dev)
R2_ACCESS_KEY_ID=your-access-key
R2_SECRET_ACCESS_KEY=your-secret-key
R2_BUCKET_NAME=your-bucket
R2_ACCOUNT_ID=your-account-id

# Screenshot API (defaults to free Screen-Shot.xyz)
SCREENSHOT_API_URL=https://api.screen-shot.xyz

pnpm run dev

​

Coding Standards

​

TypeScript

• Use TypeScript for all new code.
• Avoid any. Use unknown if the type is genuinely not known at compile time.
• Be explicit about function parameter and return types, even when inference would work.

// ✅ Correct
export function lerp(start: number, end: number, progress: number): number {
  return start + (end - start) * progress;
}

// ❌ Avoid
export function lerp(start, end, progress) {
  return start + (end - start) * progress;
}

​

React

• Use functional components with hooks — no class components.
• Prefer named exports over default exports for easier refactoring.
• Add the 'use client' directive to every component that uses browser APIs, event handlers, or Zustand.
• Keep components single-purpose — split large components into focused sub-components.

// ✅ Correct
'use client';

export function ShadowControls(): React.JSX.Element {
  const { imageShadow, setImageShadow } = useImageStore();
  // ...
}

​

Styling

​

File Naming

​

Linting

pnpm run lint        # Check for errors
pnpm run lint:fix    # Auto-fix fixable issues

​

Common Tasks

components/controls/MyNewControls.tsx

'use client';

import { useImageStore } from '@/lib/store';

export function MyNewControls(): React.JSX.Element {
  const { someValue, setSomeValue } = useImageStore();

  return (
    <div className="flex flex-col gap-2">
      {/* your UI */}
    </div>
  );
}

type: 'arc-light' | 'arc-dark' | 'macos-light' | 'my-new-style' | ...;

export const FRAME_HEADER_HEIGHTS: Record<FrameType, number> = {
  'my-new-style': 40,
  // ...
};

// lib/constants/backgrounds.ts
export interface BackgroundConfig {
  type: BackgroundType;           // 'gradient' | 'solid' | 'image'
  value: GradientKey | SolidColorKey | string;
  opacity?: number;
}

// lib/animation/presets.ts
export const ANIMATION_PRESETS: AnimationPreset[] = [
  {
    id: 'my-new-preset',
    name: 'My New Preset',
    description: 'Short description shown in the gallery',
    category: 'reveal',   // reveal | flip | perspective | orbit | depth
    duration: 1200,       // milliseconds
    tracks: [
      createTrack('Transform', 'transform', [
        createKeyframe(0,    { rotateX: -20, scale: 0.95 }, 'ease-out'),
        createKeyframe(1200, { rotateX: 0,   scale: 1.0  }, 'ease-out'),
      ]),
    ],
  },
];

import { clonePresetTracks } from '@/lib/animation/presets';

const tracks = clonePresetTracks(preset, { startTime: clip.startTime, clipId: clip.id });

​

Submitting Changes

​

Branch naming

git checkout -b feature/your-feature-name
# or
git checkout -b fix/short-bug-description

​

Conventional commits

<type>(<scope>): <short summary>

# Examples
feat(export): add watermark toggle option
fix(canvas): correct image positioning on aspect-ratio change
refactor(store): simplify EditorStoreSync effects
docs: update contributing guide setup steps

​

Pull request checklist

• pnpm run build passes with no errors
• pnpm run lint passes with no warnings
• Manually tested in the browser
• No console.error or unexpected console.warn output
• Follows the existing code style (see Coding Standards)
• PR description explains what changed, why, and how to test it
• Screenshots or a screen recording attached for any visual changes

​

Manual testing checklist

• Image upload — drag & drop and file picker
• Background changes — gradient, solid, and image types
• Device frames and border controls
• 3D perspective transforms
• Text and image overlays
• Animation presets and timeline playback
• Export — PNG, JPG, and at least one video format (MP4 or WebM)
• Copy to clipboard
• Aspect ratio changes
• Responsive layout at narrow viewport widths

​

Getting Help