brainkim
commented
3 years ago I appreciate the enthusiasm and thoughtfulness of this issue. And I unironically enjoyed pulling down your pull request and looking at the Crank.js repository spread out into all those files. However, I disagree with the idea that the core file being ~2k lines of code (most of which are comments) makes Crank difficult to read, contribute to, or build an ecosystem around.
This is largely a matter of opinion of course, and I think one of the things people leave out when they discuss their preferences for few large files or many small files is their personal practice, how they interface with code. I can understand why some people might find a lot of code in a single file to be difficult to read. Sometimes, you struggle to figure out what function or class you’re in when there are multiple abstractions in a single file, as opposed to reading the filename and getting a sense of where you are. And of course, you saw the /*** ***/ comment markers which seemed to indicate natural places to split up the file.
Nevertheless, I think it makes the most sense for the core module to be a single file. For the practical concern of getting a bigger picture of large files, I recommend code editing tools like code folding and split editing. This will likely not be your last time encountering a “large” file of code, and these techniques are indispensable for getting a sense of large files at a glance. And personally, I am a voracious reader of code, and I often browser repositories directly on GitHub to learn a particular algorithm or technique. When a library has a technique I’m interested in and flaunts a sub 5KB minzipped size but ends up strewn across multiple files, I usually end up sighing in exasperation.
Additionally, there are many reasons specific to Crank which I think makes it better as as single file.
-
While there are concrete runtime abstractions like elements, renderers, and contexts which could each be in their own file, these abstractions are mutually recursive and difficult to use independently. If you’re using elements, you’re likely using renderers and contexts. If you’re using renderers, you’re definitely using elements and likely using contexts. And if you’re using contexts, you’re certainly using both elements and renderers. In other words, if you use any part of Crank, you’re likely using all of it, so none of the abstractions are meaningful on their own. You may have noticed this when splitting up the code into various modules, insofar each of the modules circularly depends on at least the types of other modules.
-
Modules in JavaScript are not just a means of code organization, but delivery. ESModules are now being adopted, and what this means is that it’s possible, for instance, to import Crank directly in the browser thanks to unpkg or other NPM-based CDNs. What this means is that splitting up the core Crank file into multiple files can mean multiple requests. To what end? You can of course, bundle the files to reduce the number of public modules, but again, I have to ask, what is the purpose of splitting up these files in the first place if you’re just going to bring them back together with the build process.
-
It might surprise you, but I actually take pride in Crank.js’s core being a single file. I have rewritten this file about 3 or 4 times as I learned to write a web framework, and its current iteration is the result of radical and deliberate deletions and refactorings. My goal for Crank was always to write a framework which was so simple that I could rewrite it from scratch if I had to, like a soldier field stripping and reassembling a rifle, and I think I have achieved this to a certain extent. Moreover, having libraries be a single file continues in a venerable tradition, from the days of Backbone, when you could read a file and be given an explanation of its logic. A file can tell a story, insofar as it is linear, in a way which a directory of files does not. This idea is called literate programming, and it’s an idea introduced back in 1984 believe it or not. While I’m not sure yet that Crank fully meets these aspirations in having the source be self-explanatory, I do think that having the core be a single file draws us closer to these ideals.
-
Another potentially surprising detail, I consider Crank.js to be close to feature complete. The API is much more stable than you might expect. I have always strived to write code which is easy to maintain, and doesn’t require elaborate committees and RFC processes to maintain. I am skeptical of libraries which seem to continuously add features and cause major breaking redesigns. At some point, you have to ask, do these people actually know what they want? Are they happy to continue to chase trends and mind share, at the cost of the people who’ve already bought in? There are some details about coordination of async coordination and unmounting, and error handling which I’d like to iron out at some point, but I’d like for Crank to be feature complete by the end of 2022.
Some specific responses.
ESM build is spit into the root project directory, which results in any change to current module structure having to be "relayed" to package.json, .gitignore and several other files.
Yeah, I’m unhappy about this. If you have specific solutions that don’t involve splitting up Crank into a bunch of files, I’m happy to take a look. I do like the transparency of having files be exactly the same path under the root though, so I dunno.
Lack of the "unpkg" field in package.json leads to unpkg.com serving cjs version by default, instead of umd or esm.
This feels like an unpkg problem, no? I’ve done all the standard things to indicate the package is ESM first, including "type": "module", why isn’t unpkg able to pick that up?
Website and examples are embedded into the main repository, which simply results in unnecessary code for anybody willing to clone Crank and contribute to it.
It’s easy to ignore the code, and putting the website (which includes the docs) somewhere else would just make it harder to find.
"sideEffects": false
We can look into this. Like I said, if you’re using any of Crank, you’re likely to use all of it (excluding specific renderers), so tree-shaking doesn’t really make sense.
Again, thanks so much for bringing this up. I’m sure other people are thinking similar things and you encouraged me to articulate the reasons surrounding the decisions. However, the majority of the changes you propose is almost like asking me to cut my own baby in half, so it’s unlikely to ever be done. Sorry!
Raiondesu
rofrol
Preamble
I am aware that this particular topic is nothing groundbreaking and that crank is still in its early development stages. 🙂\ But this issue is going to get a higher priority as Crank gets more attention from people, so I feel like this has to be written down somewhere, for tracking purposes at least.
Current Problems
Code grouping
Crank currently has 3 main modules -
crank.ts,html.ts, anddom.ts- and a "barrel" fileindex.ts, with the bulk of the code resting incrank.ts(over 2k lines at the time of writing).This creates several maintainability issues:
Build
Current build process has several flaws:
package.json,.gitignoreand several other files."unpkg"field inpackage.jsonleads tounpkg.comservingcjsversion by default, instead ofumdoresm.Website and examples
are embedded into the main repository, which simply results in unnecessary code for anybody willing to clone Crank and contribute to it.
Possible solutions
"esm"directory be the output for theesmbuild and change the corresponding fields inpackage.jsonand other files."sideEffects": falseto improve static analysis and tree-shaking."unpkg"field.P.S. I suspect that there's a purpose/reasoning behind the current project structure, even though it doesn't seem to be stated anywhere. Even if it is true, however, problems described above still stand.