flecks/README.md

flecks

Flecks is an exceptionally extensible fullstack application production system. Its true purpose is to make application development a more joyful endeavor. Intelligent defaults combined with a highly dynamic structure encourage consistency while allowing you to easily express your own opinions.

✴️ BE WARY ✴️

This is largely untested software. There are undoubtedly many bugs that haven't yet been found.

I reserve the right to break all semantic versioning guarantees as long as the project is v1.x.x! 😈

You've been warned!

Have fun! ☺️

Table of Contents

1. Install
2. Introduction
3. Concepts

Install

Quickly scaffold a new application monorepo:

yarn create @flecks/app my-new-app

or with npm:

npx @flecks/create-app my-new-app

---

Quickly scaffold a new fleck:

yarn create @flecks/fleck my-new-fleck

or with npm:

npx @flecks/create-fleck my-new-fleck

Introduction

Modern features you expect — like

• linting
• testing
• HMR (even on server 😳)
• SSR

Things you don't expect — like

• Dynamic CLI (hooks)
• Dynamic REPL (hooks)
• Dynamic build (include @flecks/react into your fleck and watch it learn to compile JSX, even on the server side)
• Freedom to split up e.g. Redux applications into discrete slices while relying on flecks to automatically handle things like middleware, reducer composition, server/localStorage hydration, etc.
• Write a hook and surprise someone else.

Concepts

Eeez vereh flecksible 🥴

At its core, flecks is a collection of modules that use hooks to orchestrate everything from building your project to handling the minutia of what happens when your application starts, when a client connects, defining database models, and more.

Just to give you an idea of the power of hooks, some will be listed here:

• @flecks/web/server.stream.html

  Compose the server-side HTML stream. This is how SSR slides in.

• @flecks/docker.containers

  Define Docker containers to automatically come up next to your app. See @flecks/redis's implementation. @flecks/docker also generates Dockerfile and docker-compose.yml and provides the CLI command flecks docker for even more.

• @flecks/web/server.request.route

  Define Express middleware that runs when an HTTP route is hit.

• ... and many more on the hook reference page

The build directory

Flecks applications contain a build directory with a flecks.yml that defines the flecks use to compose the project, as well as build-time configuration.

Flecks strives to provide powerful defaults that minimize the need to override configuration.

The simplest example of a flecks server application:

'@flecks/core': {}
'@flecks/server': {}

Yes, that's it! In fact, when you use yarn create @flecks/app, that's what is generated for you by default.

Obviously, this doesn't do much on its own. It simply bootstraps flecks and runs a server application with no interesting work to do. It's just a jumping-off point.

Learn even more about the build directory.

---

Documentation is a work in progress ❤️