2019-06-27 06:40:38 +00:00
|
|
|
# src
|
|
|
|
|
|
|
|
Hey, welcome! This project is still very experimental so I won't make any
|
|
|
|
promises about the future architechture, but today it's pretty simple:
|
|
|
|
|
|
|
|
```
|
|
|
|
src: you are here!
|
2019-06-27 20:36:43 +00:00
|
|
|
├── assets: static resources like CSS and images
|
|
|
|
└── routes: URL handlers that integrate views with models
|
|
|
|
├── models: abstractions for working with the database
|
|
|
|
│ └── lib: code shared by models (like Markdown rendering)
|
|
|
|
└── views: page renderers that receive data and output HTML
|
|
|
|
└── components: shared components that are reused across pages
|
|
|
|
```
|
|
|
|
|
|
|
|
## Experiments
|
|
|
|
|
|
|
|
### Always forward, never back
|
|
|
|
|
|
|
|
I have a hunch that importing modules from parent directories makes it really
|
|
|
|
easy to create spaghetti code that's difficult to learn and maintain. I don't
|
|
|
|
know whether that's true, but I'm experimenting with a layer-based approach
|
|
|
|
where modules always `require('./some-layer/some-module')`. I don't know
|
|
|
|
whether this *actually* has any interesting properties, but I'm trying it out
|
|
|
|
to see whether it results in simpler software architechtures.
|
|
|
|
|
|
|
|
#### Pattern
|
|
|
|
|
|
|
|
```javascript
|
|
|
|
require('./foo/bar')
|
|
|
|
require('./lib/configurator')
|
|
|
|
require('./tools/quark-smasher')
|
|
|
|
```
|
|
|
|
|
2019-06-27 20:40:28 +00:00
|
|
|
#### Anti-pattern
|
2019-06-27 20:36:43 +00:00
|
|
|
|
|
|
|
```javascript
|
|
|
|
require('../../../great-grandparent-skyler')
|
|
|
|
require('./sibling-jamie')
|
|
|
|
require('./wat') // same as `require('./wat/index')
|
|
|
|
```
|
|
|
|
|
|
|
|
**Note:** I want to make *very* clear that this is an experiment, not a claim
|
2019-06-27 20:42:01 +00:00
|
|
|
that this is Objectively Better. It's also important to note that the essential
|
2019-06-27 20:36:43 +00:00
|
|
|
bit here is the [dependency graph][dep-graph], not the directory tree. I'm using
|
|
|
|
the directory tree as a proxy for the dependency graph because it's simple, but
|
|
|
|
the dependency graph of the following directory trees are identical:
|
|
|
|
|
|
|
|
```
|
|
|
|
├── a
|
|
|
|
└── b => c() + e()
|
|
|
|
├── c => d()
|
|
|
|
│ └── d
|
|
|
|
└── e => f()
|
|
|
|
└── f
|
|
|
|
```
|
|
|
|
|
|
|
|
```
|
|
|
|
├── a
|
|
|
|
├── b => c() + e()
|
|
|
|
├── c => d()
|
|
|
|
├── d
|
|
|
|
├── e => f()
|
|
|
|
└── f
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### Any my [hyper]axe
|
|
|
|
|
|
|
|
Converting JSON data to HTML templates is hard work. I started with Swig but
|
|
|
|
when I realized it wasn't maintained I rewrote everything in EJS. I liked it a
|
|
|
|
bit better than Swig, but JS-in-HTML still just felt clunky and wrong.
|
|
|
|
|
|
|
|
Most of my friends user HyperScript or nanohtml, but I wanted more structure.
|
|
|
|
Browsing the HyperScript readme I saw a reference to [hyperaxe][hyperaxe-gh],
|
|
|
|
which had all of the features I wanted to see:
|
|
|
|
|
|
|
|
- Compact JavaScript syntax, not HTML-in-JS (see: nanohtml)
|
|
|
|
- HTML tags as exported functions, not arbitrary strings (see: HyperScript)
|
|
|
|
- Meant to be used alone "bring your own HyperScript" (see: hyperscript-helpers)
|
|
|
|
- Uses HyperScript under the hood, which I've had lots of experience with
|
|
|
|
- Maintained by someone in my city (!) which is always a nice bonux
|
|
|
|
- Fun and friendly readme that's both light and super informative
|
|
|
|
|
|
|
|
The only bummer is that I can't find any other modules using it in production,
|
|
|
|
so I'm counting this as another experiment. It looks great and my first day with
|
|
|
|
it has been really enjoyable, but if something goes horribly wrong then we can
|
|
|
|
switch to hyperscript-helpers or something.
|
|
|
|
|
|
|
|
**Note:** I wasn't aware of hyperscript-helpers until I *after* I refactored
|
|
|
|
the templates to use hyperaxe. Oops. I think hyperaxe has a cooler name anyway.
|
|
|
|
|
|
|
|
[dep-graph]: https://en.wikipedia.org/wiki/Dependency_graph
|
|
|
|
[koa-blog]: https://github.com/koajs/examples/blob/1fd531698cc5ef21a61b627058ad0aafe9e55360/blog/lib/render.js#L13
|
|
|
|
[hyperaxe-gh]: https://github.com/ungoldman/hyperaxe
|