Guidelines:

Getting Stated

Install the CLI

You could download all the pieces from Github and setup your development environment, but there's an easier way: @composi/create-composi-app. This lets you create a project set up with everything you need. Install it from NPM:

npm i -g @composi/create-composi-app

After that you can create a new Composi project like this:

create-composi-app My-Project

This will create a project on your destop. Open the terminal, cd to the new project and run:

npm i

When the install finishes you can run npm start to build the new project and launch it in your default browser. All the important code resides in the project's dev folder. When you make changes to its contents, the project automatically re-builds and reloads the browser. The core of the project's JavaScript is in dev/js/app.js. This is where you assemble all the pieces to make your app work.

Choices

@composi/core is small but it offers a lot of functionality. This means you need to make some basic choices when you start a new project. Using @composi/create-composi/app gives you a project setup ready to use. There are several approaches you could take to build out your app, some more complicated than the others. We recommend that you start out as simple as possible. A new project comes with a Title rendered to the page. The app.js file imports h and render. That's all you need to get going.

Handling Data Needs

Hopefully you want something more than a title. You app will probably have to output some kind of collect. You need to create a view that can handle that. You'll probably want to enable the user to interact with your app. Don't bother with that at first. Just come up with a component that can render out the basic data and structure for the app. This data is a separate object in your code that you use to render the view. When you see that you've got what you expect, go back and add events, one at a time. Now the big choice is how to make your app react to events. Because you data is inert, the event will have to update it and re-render the view.

DataStore

Having events manipulate state and re-render views is messy. When your app reaches this stage, you'll probably want to look at using a dataStore. You'll need to import it into your project to use it. A dataStore gives you immutable data and updating its state can re-render the view for you. That way your events only have to update the dataStore's state.

Client Side Data Persistence

At some point you might want to enable the persistence of user interactions, such as adding or deleting items. You can do that with a dataStore through its putInLocalStorage method. Try it out. However, localStorage does have limitations: size and all data must be converted to strings. When this becomes a problem, think about instead using @composi/idb. This is an promise-based wrapper for IndexedDB that provides a simple interface similar to localStorage.

Interaction Complexity

Using a dataStore or IDB and Observers with your app may be all you need. However, if you find you have many events that have to be tracked by dataStore or Observer listeners, you may want an alternative. That would be @composi/core runtime. It's already in your project as part of @composi/core. You just need to import it in your app:

import { h, render, run} from '@composi/core'

The runtime provides an encapsulate environment with state management for your functional components. If this is your first time using @composi/core, you would want to start with one of the simpler approaches described above. When you're comfortable creating and update with functional components, take a look at how to use the runtime.

Runtime First

If you're already familiar with how to use the @composi/core runtime, then it's fine to start off right away with it. However, you should still follow steps similar to what we described before. Start off with the simplest possible implementation—render some static data. Then slowly add events to the view and actions to the update function. Gradually refactor to incease the complexity. That way if something breaks, you know where to look.

Remember, all you need to make a valid runtime program is this:

import { h, render, run } from '@composi/core'
const program = {
  init: [],
  update() {},
  view() {}
}
// run the program
run(program)

And here it is live!

See the Pen @composi/core + runtime Basic by Robert Biggs (@rbiggs) on CodePen.

Start simple. Then add a static view. Then add an event and an action to handle it. Keep it all in one file at first. As the program grows in complexity, move parts out into their own files.