By name: fabric-js description: "[Applies to: **/*.{js,jsx}] This guide outlines definitive best practices for using fabric-js (v6.9.0+) in JavaScript/TypeScript projects, focusing on performance, maintainability, and modern API usage." source: "cursor_mdc"
fabric-js Best Practices
This document provides definitive guidelines for developing with fabric-js (v6.9.0+), emphasizing performance, maintainability, and modern API adoption. Adhere to these rules to ensure robust and efficient canvas applications.
1. Code Organization and Structure
1.1. Embrace TypeScript and ES Modules
Always use TypeScript for type safety and leverage ES6 modules for efficient bundling. Import only the specific fabric components you need.
❌ BAD: Global fabric access, full library import
// main.js
import 'fabric'; // Imports everything
const canvas = new fabric.Canvas('myCanvas');
canvas.add(new fabric.Rect({ left: 10, top: 10, width: 50, height: 50 }));
✅ GOOD: Modular, typed imports
// main.ts
import { Canvas, Rect, IText } from 'fabric';
const canvas = new Canvas('myCanvas');
const rect = new Rect({ left: 10, top: 10, width: 50, height: 50, fill: 'red' });
canvas.add(rect);
1.2. Choose the Right Canvas Type
Use StaticCanvas for read-only displays or high-frame-rate scenes where interactivity is not required. It offers a significant performance boost by skipping event handling.
❌ BAD: Using Canvas when no interaction is needed
// For displaying a static image or animation without user interaction
const canvas = new Canvas('myStaticCanvas');
canvas.add(someFabricObject);
canvas.renderAll();
✅ GOOD: Using StaticCanvas for static or high-performance rendering
// For displaying a static image or animation without user interaction
import { StaticCanvas, Rect } from 'fabric';
const staticCanvas = new StaticCanvas('myStaticCanvas');
const rect = new Rect({ left: 10, top: 10, width: 50, height: 50, fill: 'blue' });
staticCanvas.add(rect);
staticCanvas.renderAll();
2. Performance Considerations
2.1. Disable Unnecessary Interactivity
Minimize overhead by disabling selection, controls, and borders on objects or the canvas itself when not needed.
❌ BAD: Default interactive objects everywhere
const rect = new Rect({ left: 10, top: 10, width: 50, height: 50, fill: 'green' });
canvas.add(rect); // Selectable, has controls/borders by default
✅ GOOD: Optimize object interactivity
const rect = new Rect({
left: 10, top: 10, width: 50, height: 50, fill: 'green',
selectable: false, // No selection
hasControls: false, // No scaling/rotation controls
hasBorders: false, // No bounding box borders
hasRotatingPoint: false, // No rotating point
});
canvas.add(rect);
// Disable canvas-wide selection if not needed
canvas.selection = false;
2.2. Leverage Object Caching
Enable objectCaching for complex objects (e.g., paths, filtered images, groups) to pre-rasterize them, avoiding repeated expensive drawing operations.
❌ BAD: Complex object without caching
import { Path } from 'fabric';
const complexPath = new Path('M 0 0 L 100 0 L 50 100 z', { fill: 'purple' });
canvas.add(complexPath); // Rerendered every time
✅ GOOD: Enable object caching for performance
import { Path } from 'fabric';
const complexPath = new Path('M 0 0 L 100 0 L 50 100 z', {
fill: 'purple',
objectCaching: true, // Cache complex path as a bitmap
});
canvas.add(complexPath);
2.3. Optimize Batch Operations
When adding or removing many objects, disable renderOnAddRemove to prevent unnecessary re-renders for each operation. Manually call canvas.renderAll() once after all changes.
❌ BAD: Multiple renders for batch operations
for (let i = 0; i < 100; i++) {
canvas.add(new Rect({ left: i * 2, top: i * 2, width: 10, height: 10 }));
} // canvas.renderAll() called 100 times
✅ GOOD: Batch operations with single render
canvas.renderOnAddRemove = false; // Disable auto-render
for (let i = 0; i < 100; i++) {
canvas.add(new Rect({ left: i * 2, top: i * 2, width: 10, height: 10 }));
}
canvas.renderOnAddRemove = true; // Re-enable if needed later
canvas.renderAll(); // Render once after all additions
2.4. Manage Object Visibility
Set object.visible = false for objects outside the current viewport or not intended to be seen, preventing them from being drawn.
const offScreenRect = new Rect({ left: 1000, top: 1000, width: 50, height: 50 });
offScreenRect.visible = false; // Prevents rendering when off-screen
canvas.add(offScreenRect);
3. Common Patterns and Anti-patterns
3.1. Use Modern Accessors
Always use getScaledWidth() and getScaledHeight() to retrieve an object's dimensions, as getWidth() and getHeight() are deprecated.
❌ BAD: Using deprecated accessors
const rect = new Rect({ width: 100, height: 50, scaleX: 2 });
console.log(rect.getWidth()); // Throws error in v2+
✅ GOOD: Using modern accessors
const rect = new Rect({ width: 100, height: 50, scaleX: 2 });
console.log(rect.getScaledWidth()); // Outputs 200
console.log(rect.getScaledHeight()); // Outputs 50
3.2. Prefer fabric.Group over fabric.PathGroup
fabric.PathGroup is obsolete. Use fabric.Group for all object grouping, including SVG imports.
❌ BAD: Using fabric.PathGroup
// This class no longer exists in modern Fabric.js
const pathGroup = new fabric.PathGroup([path1, path2]);
✅ GOOD: Using fabric.Group
import { Group, Rect, Circle } from 'fabric';
const rect = new Rect({ width: 50, height: 50, fill: 'red' });
const circle = new Circle({ radius: 25, fill: 'blue' });
const group = new Group([rect, circle], { left: 100, top: 100 });
canvas.add(group);
3.3. Correct Image Filter Application
applyFilters is now synchronous. Call canvas.requestRenderAll() (or renderAll()) after applying filters to update the canvas.
❌ BAD: Old async filter syntax
// This will throw an error
image.applyFilters(canvas.renderAll.bind(canvas));
✅ GOOD: Modern sync filter application
import { FabricImage, Image } from 'fabric';
FabricImage.fromURL('path/to/image.png', (img) => {
img.filters.push(new Image.filters.Grayscale());
img.applyFilters(); // Synchronous
canvas.add(img);
canvas.requestRenderAll(); // Request a render after filters are applied
});
3.4. Serialize Canvas State Reliably
Always use canvas.toJSON() for serialization. If you have custom properties, ensure they are included in toObject methods of your custom classes. Version your JSON schema for future compatibility.
// Save canvas state
const jsonState = canvas.toJSON(['customProperty1', 'customProperty2']);
localStorage.setItem('canvasState', JSON.stringify(jsonState));
// Load canvas state
const savedState = JSON.parse(localStorage.getItem('canvasState'));
canvas.loadFromJSON(savedState, () => {
canvas.renderAll();
console.log('Canvas loaded from JSON');
});
4. Testing Approaches
4.1. Benchmark Rendering Performance
Regularly benchmark canvas.renderAll() to identify performance regressions, especially after significant changes or adding complex objects.
console.time('renderDuration');
canvas.renderAll();
console.timeEnd('renderDuration'); // Log render time
4.2. Test on Both Canvas Types
If your application uses both Canvas and StaticCanvas (e.g., for editing vs. display modes), ensure all features and objects render correctly on both.