Composi

Composi is a framework for creating desktop and mobile apps. With Composi you can create a dynamic website with reactive components, a progressive web app, or a hybrid app for mobile app stores. Visit the website.

Composi is small. The core is barely 3KB gzipped. It therefore loads fast. Its virtual DOM updates components efficiently and quickly. It has an API very similar to React, while mainting it's emphasis on simplicity, size, and ease of learning. In fact, you can learn everything you need to know to build apps with Composi in an hour or two.

Composi components can be stateless or stateful. Stateful components are reactive. When you change a component's state, that triggers the component's render function. That in turn creates a new virtual DOM based on the data changes. It then patches the DOM to match the changes. If there are no changes, nothing will happen.

A component's markup is written with JSX. This means you can create custom tags to organize your component's template. You can also pass props to a component tag. If you prefer, you can instead use the h function to define the component's markup with hyperscript. In fact, at render time the JSX is converted to this.

Browser Support

Composi is compatible with browsers back to IE 9 on Windows 7, although you may need to include a polyfill for promises for complete compatibility.

Live Examples on Codepen

1. Todo List
2. Minimal Hacker News
3. Tour of Heroes (Client Side Routing)s
4. Calculator
5. Cat Image Browser
6. Pythagoras Dancing Tree
7. Tic-Tac-Toe
8. Rick and Morty Character Viewer
9. Slideshow Component
10. Coin Flip App
11. Canvas Clock
12. SVG Clock
13. Spreadsheet
14. Counter with Redux
15. Counter with Mobx

Installation

To install Composi, you'll need to have Nodejs installed. Open your terminal and run:

npm i -g composi

Note: On macOS and Linux, you may need to run the above command with sudo.

Create a New Project

After installing Composi, you can use it to create a new project. The simplest way to do this is to provide a project name following the -n flag:

composi -n myproject

This will create a project named "myproject" on your desktop. If you want to have the project placed somewhere else, you can provide a path with the -p flag:

npm -n myproject -p dev/New \Projects

On Windows use the standard Windows file system path notation to define your project's path.

Project Structure

A new project will have the following folder structure:

+--myproject
|  +--dev
|     +--components
|        |--title.js
|     +--css
|        |--styles.css
|     |--app.js
|  +--js
|--.babelrc
|--.editorconfig
|--gulpfile.js
|--index.html
|--package.json
|--README.md

Building

To build your project, cd to its folder and run:

npm i

Then, while in your project's root folder, run:

npm start

This will build and launch your project in your default browser.

With this structure, you can add other sub-folders to components, or create other folders inside the dev folder as necessary.

styles.css is a CSS reset. We are using the Bootstrap 4 rest since it provides a consistent baseline for HTML across all browsers. app.js is the core of your website/app. components folder has one component: list.js. You can add more files for other component as needs. Feel free to add more folders and files to the dev folder as you see fit to achieve the structure your app needs. Import them into app.js. At build time the build script uses app.js to bundle all your files and output them to js/app.js. The index.html is automatically setup to import that script. index.html is your main page.

Example Code - Functional Component

import { h, mount } from 'composi'

function HelloWorld({name}) {
  return (
    <nav>
      <h1>Hello, {name}!</h1>
    </nav>
  )
}

mount(<HelloWorld name='World' />, 'header')

Example Code - Class Component

import { h, Component } from 'composi'
import { sampleData } from './data/sample-data'

class List extends Component {
  render(data) {
    return (
      <ul class='list'>
        {
          data.map(item => <li key={item.key}>{item.name}</li>)
        }
      </ul>
    )
  }
}

// Instantiate class to render component to DOM:
new List({
  container: 'section',
  state: sampleData
})

Documentation

To learn how to use Composi, open the docs folder.

Summary

Composi is all about components. These provide a great way to organize your code into modular and reusable chunks. The virtual DOM means you never have to touch the DOM to change something.

Because Composi uses JSX, there are many similarities to React patterns. Please note that Composi is not a React clone. It is not trying to be compatible with React and the React ecosystem the way Preact and Inferno do. Component state is managed quite differently from React. Components lack the React refs and context properties. Also lacking, PropTypes. Events are not synthetic. They are either real inline events or the handleEvent interface. Props and custom tags are supported only because JSX provides these by default. The component architecture is actually adapted from the Component class of ChocolateChip-UI. Changes were made to the API to work with a virtual DOM.

Composi is small, just 3KB for the gzipped core. It loads quickly. Its small and focused API means you can learn everything in half a day and be productive. If you're already familiar with JSX, then you only need to learn the Component API. You can easily do that in an hour.

Running Tests

Composi comes with unit test written with Mocha and Chai. These are loaded from a CDN, so you require an internet connect to run these tests. To run them, open your terminal and execute:

npm test

This will open a navigation page in your default browser. There are four tests:

1. h
2. fragment
3. mount and render
4. Component

Clicking on one of these will open the test page. The test runs automatically when you open the page. Some errors may only show in the browser console, so open it to check. You can get back to the test navigation page by clicking any where on the top header.

What's Missing

Composi is focused on one thing - providing a solution for components for building and structureing a projects. That means there are certain things it does not address, such as state management, routing, Ajax, and data persistence. There are already solutions that provide these, as enumerated below.

State Management

Composi provides the barest support for state through the component's state property and setState method. However for a more robust solution you may prefer to use Redux, Mobx, or some other state management solution. When you do so, you'll want to create stateless components. Read the documentation for Component to learn more about stateless components. If yo want something really minimal, take a look at trkl and pure. You could event roll your own state management solution by defining a class and using Composi's pubsub functions, subscribe and dispatch for making it reactive. Another possibility for state management is freezer-js

Router

Composi does not provide a client-side router. However, you can use our blessed router composi-router. The Github repository has documentation on how to use.

Other alternatives for client-side routing are Page.js, Universal Router, Navigo or rlite-router.

Ajax

Composi does not provide a means of aquiring remote data. If you only need to support current, ever-green browsers, you an use fectch. If you would like to use fetch with older browsers, you can provide the WHATWG polyfill. If don't need every possible feature of fetch and are concerned about the polyfill size, you can consider unfetch. It's tiny and provides good support for the basics.

If you would prefer an approach more like tradition Ajax championed by jQuery, you can take a look at Axios.

Local Data Persistence

If you need to persist data locally, you could use the browser's localStorage. If you need greater storage or a more sophisticated API, you might look at IndexedDB. If you need support for older browsers, you might consider localForage. This is a libarary that uses whatever local dataStore is the best choice for the browser. It provides a simple interface that works the same for localStorage, WebSQL and IndexedDB.

Prior Art

Composi was not conceived in a vacuum. Inspiration came for exposure to:

1. vue
2. react
3. preact
4. domvm
5. yo-yo
6. choo
7. hyperapp