Famous (Legacy) Deployment & Usage Guide

DEPRECATION WARNING: This repository is deprecated and no longer maintained. For new projects, use the Famous Engine (Mixed Mode). This guide is for legacy maintenance only. Documentation for this version is archived at http://deprecated.famous.org.

Prerequisites

Runtime: Modern web browser with CSS3D transforms support (Chrome, Firefox, Safari, Edge)
Module Loader: RequireJS or Almond (AMD module system)
Server: Local HTTP server capability (Python, Node.js http-server, or similar) required due to CORS restrictions on AMD modules
Build Tools (optional): Node.js and npm for production optimization with r.js

Installation

Clone the legacy repository:

git clone https://github.com/Famous/famous.git
cd famous

For existing projects using Bower (typical for 2015-era projects):

bower install Famous/famous

Configuration

Configure RequireJS to resolve Famous module paths. Create or update your main.js or app.js entry point:

require.config({
    baseUrl: '.',
    paths: {
        'famous': 'path/to/famous/src',
        'famous-core': 'path/to/famous/src/core',
        'famous-views': 'path/to/famous/src/views',
        'famous-physics': 'path/to/famous/src/physics',
        'famous-inputs': 'path/to/famous/src/inputs',
        'famous-utilities': 'path/to/famous/src/utilities',
        'famous-transitions': 'path/to/famous/src/transitions'
    }
});

Note: Adjust path/to/famous to match your actual directory structure (e.g., bower_components/famous or ./famous).

Build & Run

Development

No build step is required for development. Serve the directory via HTTP:

# Python 3
python -m http.server 8000

# Node.js
npx http-server -p 8000

# PHP
php -S localhost:8000

Basic Usage Example

Create an HTML file and JavaScript entry point using the core components:

index.html:

<!DOCTYPE html>
<html>
<head>
    <script src="require.js" data-main="app.js"></script>
    <style>
        body { margin: 0; overflow: hidden; }
        .famous-surface { display: flex; align-items: center; justify-content: center; }
    </style>
</head>
<body></body>
</html>

app.js:

require([
    'famous-core/Surface',
    'famous-core/Modifier',
    'famous-core/Transform',
    'famous-views/Scrollview',
    'famous-physics/PhysicsEngine',
    'famous-core/Engine'  // If available in your version
], function(Surface, Modifier, Transform, Scrollview, PhysicsEngine, Engine) {
    
    // Create context (assuming Engine is available)
    var context = Engine.createContext();
    
    // Example 1: Basic Surface with Modifier
    var surface = new Surface({
        size: [200, 200],
        content: 'Legacy Famous',
        properties: {
            backgroundColor: '#FA5C4F',
            color: 'white',
            borderRadius: '10px'
        }
    });
    
    var modifier = new Modifier({
        transform: Transform.translate(100, 100, 0),
        origin: [0.5, 0.5]
    });
    
    context.add(modifier).add(surface);
    
    // Example 2: Scrollview with Physics
    var scrollview = new Scrollview({
        direction: 1  // Utility.Direction.Y (vertical)
    });
    
    var surfaces = [];
    for (var i = 0; i < 20; i++) {
        var s = new Surface({
            size: [undefined, 100],
            content: 'Item ' + i,
            properties: {
                backgroundColor: '#f0f0f0',
                borderBottom: '1px solid #ccc',
                lineHeight: '100px',
                textAlign: 'center'
            }
        });
        s.pipe(scrollview);
        surfaces.push(s);
    }
    scrollview.sequenceFrom(surfaces);
    
    context.add(scrollview);
});

Production Build

Optimize AMD modules using r.js:

npm install -g requirejs
r.js -o build.js

Example build.js:

({
    baseUrl: ".",
    paths: {
        'famous': 'famous/src'
    },
    name: "app",
    out: "app.built.js"
})

Update HTML to use the built file:

<script src="app.built.js"></script>

Deployment

Deploy as static files to any web hosting platform:

Recommended Platforms:

GitHub Pages: Drag-and-drop the built directory
Netlify: Connect repository or use netlify deploy --prod --dir=./
Vercel: Use vercel --prod or connect Git repository
AWS S3: Upload to S3 bucket with static website hosting enabled
Traditional Hosting: Upload via FTP/SFTP

Important: Ensure Content-Type: application/javascript headers are set for .js files. Some servers may require configuration for AMD module loading.

Troubleshooting

"Module not found" errors

Verify RequireJS paths match the src/ directory structure exactly. The library uses nested paths like famous/src/core/Transform.

CSS3D transforms not working

Check browser console for transform-style: preserve-3d support. Some mobile browsers require vendor prefixes that this version of Famous may not automatically handle.

Physics simulation lag

The PhysicsEngine uses Date.now() for timing. Ensure your device clock is stable and the tab remains active (browsers throttle inactive tabs).

Migration to Modern Famous

To migrate to the supported version:

Visit https://github.com/famous/engine
Note that the API changed significantly (Mixed Mode uses WebGL + DOM)
Join Famous Community Slack for migration support

"This repo is deprecated" warnings

This is expected. The repository is frozen at the 2015 state. Do not expect patches or security updates. Consider migrating to the new Engine or alternative frameworks (React, Vue, Svelte with CSS animations).

Module loading issues in Chrome

Chrome restricts file:// protocol access for AMD modules. You must use an HTTP server (see Build & Run section) rather than opening index.html directly.

How to Deploy & Use Famous/famous