Installation

Composi is Small

When you install Composi you are only adding 3KB to your final project's JavaScript. That means a simple Hello World app's JavaScript will be only 3KB. Composi's small size means it loads quickly, even on old phones with poor connections. Despite its small size, Composi offers a lot of functionality to create complex and powerful applications. This means most of the JavaScript your project needs to load should be code you wrote, not library bloat. In the world of mobile and PWAs, small is beautiful.

Install from NPM

To install Composi, you'll need to have Node installed first. If you do have Node, then open your terminal and run:

npm i -g composi

If you are on a Mac or Linux, you may need to run the above command with sudo.

Once the installation is complete, you are ready to create your first project.

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

If you want to create a project with a name with spaces, you will need to quote it. Similarly, you can use uppercase letters as well. For names with spaces, Composi with convert those to hyphens to comply with NPM naming conventions. In your project's html file the name will appear as you entered. Similarly, if you provide a name with uppercase letters, Composi will convert those to lowercase for NPM compatibility. But in your project's html file the name will appear as you entered it.

composi -n "My Project"

Provide a Path

When you create a new project providing a name with the -n flag, Composi creates this on your Desktop. If you would like the new project to be output somewhere else, you can provide the -p flag followed by a valid path to where you want your project. You will need to provide a path for the operating system on which you are working, whether Mac, Windows or Linux.

 # Output new project to path:
composi -n myproject -p ~/projects

# or:
composi -n myproject -p ~/dev

If a project of the same name already exists at the destination, it will be replaced with the new project version.

After creating a project, open the folder and take a look inside. You should see a structure like this:

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

Intall Project Dependencies

After creating a project, use your terminal to cd to your project and install its dependencies:

npm i

You will spend most of your time working in your project's dev folder. When you build your project, Composi will take the files in the dev folder, bundle them, transpile the bundle and output it to your project's js folder as app.js. The index.html file is already set up to import that bundle.

The core of your app is the app.js file in the dev folder. This is where you assemble all the pieces together.

Building

After creating a project, you can build it. This will bundle all the dependencies, transpile them and put the resulting bundle in the project's js folder. To build, make sure you terminal is in your project using cd. Then run:

// Build and run app in browsers:
npm start

This will also start a Node server instance and launch the project in your default browser. If you'd like to use a different browser, you can do so by opening your project's gulpfile.js. look for the gulp task called "serve". In the Browsersync configuration you can add a property for browser with the browser you want the project build to use. The naming convention for browsers in the configuration vary by operating system. To learn more about configuring Browsersync, read the docs.

Load from CDN

If you want, you can skip the NPM install and load Composi directly from Github. Doing so means you will not be able to use ES6, JSX, etc. on older browsers. However, you can write components using the h function in hyperscript fashion.

To use it from a CDN, just import Composi with a scritp tag:

<script src='https://unpkg.com/composi@latest/dist/composi.js'></script>

You can then use Composi using its h function to define markup. Here's a simple Hello World:

<script src='https://unpkg.com/composi@1.0.0/dist/composi.js'></script>
<script>
  // get h and Component:
  var h = composi.h
  var Component = composi.Component

  // Create component:
  class Hello extends Component {
    container = 'body'
    render(name) {
      return h('h1', {}, `Hello, ${name}!`)
    }
  }
  const hello = new Hello()
  hello.setState('Joe')
</script>

For more information about how to use h, read its documentation, as well as the tutorial about using Composi without JSX.