entyre v0.0.9
Entyre
Entyre
is built around the concept of a Single File Package (SFP), inspired by
Vue.js's Single File Components. Instead of
packages having X number of javascript files, a package.json, a readme.md,
and other files for publishing, instead a package should be able to be made of a
single file. In
Entyre's
case this single file is an index.md (perhaps in the future a readme.md.
NOTICE: Active Development
Entyre is still in its early stages of development. Feel free to watch this project as it grows.
Nothing in this project promises to be stable until we reach v0.1.0.
Inception
Over the past few months I have decided to start working on a monorepo for ALL of my projects. The amount of overhead to start a new project was always massive. You could prototype and publish quickly, but for all the Developer Experience related stuff like compilation, formatting, githooks, publishing, changelogs, versioning, testing, etc. it is just a painful experience. A monorepo approach removed this problem for me. So I started working on a tool called KI/KD inspired by Lerna that would serve as a monorepo tool for an entire "company" of one developer. The goal was to be able to match Google's monorepo approach and efficiency in providing new products to the world.
Over time, I discovered that I was able to reduce each package into a single
index.js file with no package.json for just use in development. For
publishing though, I still needed
KI/KD
to create a package.json to track the versioning and a readme.md because
publishing to NPM without a readme.md is dumb. While at Vue Conf US 2018 in
New Orleans, I had come up with a cool idea to mix
Literate Programming
into my build system to be able to write docs with my code because I was running
into a problem where I had 60+ potential packages, but I had no documentation
for ANY of them. One night out drinking, something clicked.
Vue.js Single File Components, were just a bunch of
"sections" in a single file that were marked. At that moment I realized that I
could literally make Single File Packages if I combined the concept of
Front Matter from static site generators like
Jekyll with
Literate Programming
where code was in "sections" and the package.json was in its own "section".
And the rest is history.
SFP Example
A single file is a markdown file that looks like the following:
Parts
The single file is made up of several parts:
Front Matter
This concept is borrowed from static site generators... like Jekyll. The core concept is that at the beginning of a markdown document, one can define its metadata via yaml properties in a fenced block. From above, this is the Front Matter:
---
version: 0.0.1
license: MIT
description: Description of the package to be published.
---In
Entyre
Front Matter is used to define the equivalent of a package's package.json
file. Tools working with SFPs will auto modify this Front Matter with
new versions or new dependencies. With this metadata other files could be
included, like a particular LICENSE file in the final compilation.
Code Blocks
The next major piece is borrowed from Literate Programming, well a more rudimentary version of Literate Programming. The idea is that your SFP's code blocks are your code interspersed within the document. Your file is docs first, code second. This allows you to give full context to a given package's code and it sits right next to the documentation for it. The code will never fall out of sync, but the docs may have to be updated here and there. Entyre preprocesses the SFP and extracts all of the code blocks as the actual code before running it through Babel to run the code.
The Readme
Outside of that, the ENTIRE (get it?) file is your readme.md document and the
only place you work. Docs, package.json, and code all in one sweet place.
Prior Art
Thank you to the following projects:
- Literate Programming by Donald Knuth - Wonderful idea to combine docs and code to change the design experience of coding
- lit-node by Rich Harris - Used his compile code as a starting point
- Vue.js - For introducing the powerful Single File Component concept and the amazing US Vue Conf 2018 in New Orleans
- Jekyll - And other static generators for the concept of Front Matter
- Babel - Thank you for an amazing transpilation tool