littlebag

[!NOTE] littlebag is not production-ready yet. Feel free to build your hobby projects with littlebag and open issues/PRs to help the framework grow, any feedback will be appreciated!

littlebag aims to be the most lightweight web framework. It provides vital functions for managing reactive state and creating HTML components while being just ~340 bytes minified and compressed.

Ideology

• Minimal size. littlebag was built with size in mind from the ground up. It's functions are almost code-golfed which not only reduces the bundled size, but also allows to think about the framework in a different way by filtering out things that are not really needed.

• Functional programming. Components can be written as plain functions, which can be called just like usual, allowing for concise and readable code:

  function Component({ text }) {
    return html("span", {}, [text]);
  }
  
  function App() {
    return html("div", { className: "container" }, [
      Component({ text: "Hello world" })
    ]);
  }

• No unnecessary abstraction. All components are basically node factories with reactive states. That means there is no need for a separate mount function — you can just append the returned node (unless the node needs to be removed later):

  function App() {
    return html("button", {}, ["Click me!"]);
  }
  
  document.body.append(App());

• Granular reactivity. It is strongly encouraged to use primitive state instead of compound objects. This allows to only update the things that actually changed, leaving everything else intact.

  In fact, if you use TypeScript, trying to create a state with an object type will result in a type error.

Tutorial

Say you want to create a TODO list app. You don't want the pain of vanilla JavaScript, but you are too handsome and heroic to use bloated a web framework, so you choose littlebag.

You start with a simple layout using html:

function TodoItem({ text, done }) {
  return html("li", {}, [
    html("input", { type: "checkbox", checked: done }, []),
    html("input", { value: text }, []),
    html("button", {}, ["❌"])
  ]);
}

function App() {
  return html("div", {}, [
    html("h1", {}, ["TODO list"]),
    html("ul", {}, [
      TodoItem({ text: "Do the chores", done: false }),
      TodoItem({ text: "Pet my cat", done: true })
    ])
  ]);
}

document.body.append(App());

Add some reactivity with state and on*:

function TodoItem({
  text: [text, setText],
  done: [done, setDone]
}) {
  return html("li", {}, [
    html("input", {
      type: "checkbox",
      onchange: (ev) => setDone(ev.target.checked),
      checked: done
    }, []),
    html("input", {
      style: () => done() ? "text-decoration: line-through" : "",
      oninput: (ev) => setText(ev.target.value),
      value: text
    }, []),
    html("button", {}, ["❌"])
  ]);
}

function App() {
  return html("div", {}, [
    html("h1", {}, ["TODO list"]),
    html("ul", {}, [
      TodoItem({ text: state("Do the chores"), done: state(false) }),
      TodoItem({ text: state("Pet my cat"), done: state(true) })
    ])
  ]);
}

document.body.append(App());

Then use each to make a reactive list:

function TodoItem({
  text: [text, setText],
  done: [done, setDone],
  onremove
}) {
  return html("li", {}, [
    html("input", {
      type: "checkbox",
      onchange: (ev) => setDone(ev.target.checked),
      checked: done
    }, []),
    html("input", {
      style: () => done() ? "text-decoration: line-through" : "",
      oninput: (ev) => setText(ev.target.value),
      value: text
    }, []),
    html("button", { onclick: onremove }, ["❌"])
  ]);
}

function App() {
  const [todos, setTodos] = state([
    { text: state("Do the chores"), done: state(false) },
    { text: state("Pet my cat"), done: state(true) }
  ]);

  return html("div", {}, [
    html("h1", {}, ["TODO list"]),
    html("ul", {}, [
      each(todos, (todo) => {
        const [text] = todo.text;
        return TodoItem({
          ...todo,
          onremove() {
            setTodos(
              todos().filter(
                ({ text: [otherText] }) => otherText() !== text()
              )
            );
          }
        })
      })
    ])
  ]);
}

document.body.append(App());

And finally let's add a congratulation message for those lucky people who did all their TODOs!

function TodoItem({
  text: [text, setText],
  done: [done, setDone],
  onremove
}) {
  return html("li", {}, [
    html("input", {
      type: "checkbox",
      onchange: (ev) => setDone(ev.target.checked),
      checked: done
    }, []),
    html("input", {
      style: () => done() ? "text-decoration: line-through" : "",
      oninput: (ev) => setText(ev.target.value),
      value: text
    }, []),
    html("button", { onclick: onremove }, ["❌"])
  ]);
}

function App() {
  const [todos, setTodos] = state([
    { text: state("Do the chores"), done: state(false) },
    { text: state("Pet my cat"), done: state(true) }
  ]);

  return html("div", {}, [
    html("h1", {}, ["TODO list"]),
    keyed(
      () => todos().length === 0,
      (empty) =>
        empty
          ? "Everything's done 🎉"
          : html("ul", {}, [
              each(todos, (todo) => {
                const [text] = todo.text;
                return TodoItem({
                  ...todo,
                  onremove() {
                    setTodos(
                      todos().filter(
                        ({ text: [otherText] }) => otherText() !== text()
                      )
                    );
                  }
                })
              })
            ])
    )
  ]);
}

document.body.append(App());

Voilà! Here is your first little reactive app using littlebag.

Code structure

See the contributing guide for a description of the code structure and explanations of how to read (write) it.