Roadmap for v1.0.0

[jbmoelker]

Hi Elder team! Congrats on all the hard work so far! I'm very curious if you have a roadmap - things you think should be added, changed or removed to Elder - before releasing a stable v1.0.0. What are your ideas?

Imho more functionality can always be added later. So while I think short codes (#29) could be a great addition, I personally think they could wait. On the other hand, I think it's very important to reduce the API surface of Elder to a minimum before releasing v1.0.0 as that makes it easier to change things under the hood without developers using the framework being affected. So to me issues like simplifying elder.config.js (#27) and hiding the internals of rollup.config.js (#30) are important to get right before many start using the framework and expect a stable experience.

What are your thoughts?

[nickreese]

v1 Goals:

I 100% agree that 'stabilizing' the API surface should be the goal of v1.

A Robust Plugins Story:

The biggest blocker for v1 in my mind is a fully thought out plugin story. How plugins interact with the API really needs more people than just myself investigating before I'd be comfortable saying the API is 'stable'. (lots more below)

Rollup Internalization:

I'll share my experience more in the other thread #30, but I do believe internalizing the default configs should be a part of v1 but how we offer customization also needs to be considered. I just know across the 4 different Elder.js projects, we tend to have slightly configs due to decisions that predate Elder.js. (Mainly having to do with replacing values in Svelte files.) There are also questions around esm/system and how users could write CSS emitted from svelte to static files instead of tossing it in the head discussed in the other thread.

elder.config.js finalization

Agreed on simplifying this as discussed here: #27. Long term can probably depreciate the automagical stuff and possibly remove some of the debug stuff to use the debug package but that can be post v1.

Shortcode Functionality in the Core:

Internally we need shortcodes across our 4 different Elder.js sites, so it's a priority for us. I've also found that shortcodes are key to a good plugin story so they go hand in hand. The further I get down the pipe here the more I realize that Shortcodes are actually a major API surface area that should be considered as a part of the whole. Not much left on this besides developing it out. I feel good about this spec. #29

Stack/Hook Priority

Just yesterday I fixed a bug where Elder.js was sorting stacks where 100 being highest prio and 1 being lowest which is the reverse of what is documented and intended.

As humans we are so accustom to 1 being low and 100 being high that when Filip when wrote the tests didn't even realize it was a bug lol and when I reviewed it I didn't spot it either.

I've wondered for a long time about this decision and I think the priority should be flipped before v1. Plugins and Elder.js would always be enforced in to abide by the 1-100 scale, but users could go over 100 or below 0 in their hooks making sure they always have control of what runs first/last.

Removal modifyCustomProps hook:

Initially the idea was to allow people to customize what props are passed into hook functions and possibly add new props, but this is just a bad design. So far I've found 0 people using these hooks and I've also found 0 need for it personally. Most of the problems they solve are better solved with hooks and/or plugins. We should rip these out (or comment them out) until this is more thought through.

Customization to the HTML tag

I know this is something that you (@jbmoelker) brought up. If we're finalizing surface area, let's do it now. One place would be in the elder.config.js under a htmlTag key or something.

Removal of Support for hooks in route.js files.

This just API surface and has little benefit when the user can just write a standard hook and check the request.route === 'foo' to limit the scope of a hook. Initially we had some hooks in our route.js files, but today we've centralized them to keep the complexity down.

Rework/Remove link() function available in templates

Currently all Svelte templates get a link() function which is a quick way to pass in a request object and get the permalink. The biggest problem is that it isn't designed to be hydrated and it just feels like API debt offering it as a prop to the templates. I believe this should be moved to the helpers object or moved to a plugin as it doesn't feel like part of the core to me.

A Fully Thought out Plugin Story:

In my view, plugins are the foundation for offering themes or pluggable pages such as contact forms. I also see them as the key to really building a community around Elder.js.

That said, over the past couple weeks but I've managed to port my personal site, nicholasreese.com to 100% Elder.js.

My goal has been 2 fold:

1. To really understand the ins and outs of building plugins with our current implementation.
2. Long term to use my site as the foundation of a future blogging template (discussed later).

In this process I started developing both the markdown and images plugins and really realized how much shortcodes will be required for plugins to offer easily packaged user functionality.

Plugins I'm Currently Developing:

Here are the plugins I'm currently developing in addition to the already published @elderjs/plugin-sitemap, @elderjs/plugin-critical-path-css and @elderjs/plugin-browser-reload.

• @elderjs/plugin-markdown: I've got this plugin into 'alpha' and will be deploying it across 2 different properties and migrating our internal CMS to markdown over the next 3 weeks. My hunch is that there are some changes we may encounter as we roll this plugin that help more fully develop out the plugin story.
• @elderjs/plugin-images I've got a working PoC/alpha version of a plugin that offers most of the same functionality as the Gatsby plugin gatsby-images. You can see the effects of it on my personal website. Releasing this plugin will need the elder.config.js to be finalized and shortcode support to be finalized. Centralizing shortcodes into the Elder.js core will allow the markdown and images plugins to play nicely together. Without it they'll be hamstrung.
• @elderjs/plugin-random This basically allows for randomly previewing a page of a specific route. For instance, /random/nursingHomes/ in development mode on ElderGuide.com will take you to 1 of 16k nursing homes so you can see how the pages look. This is discussed a little in the rollup discussion, but I want to fully understand how plugins can ship Svelte templates. In a perfect world this plugin would add it's own random route which would include links to all of the /random/[routeName]/ pages but currently this isn't supported because it hasn't been implemented in the rollup config.

Specific Things to Be Thought About for plugins:

1. Because of our multi-threaded build process, plugins can't share their closure scope across processes. As this is the main way plugins can store data (aside from writing to a file and dealing with locking, etc) this needs to be clearly documented. So far I haven't found anything that wasn't navigable with plugins but it did throw me for a loop when building the sitemap plugin. (A possible solution after v1 is to offer an event emitter that is brokered across processes by the master process defined in build.ts.)
2. There is a community desire for incremental builds and as plugins can overwrite the allRequests object and basically force an incremental build as I do in the @elderjs/plugin-critical-path-css... we should finalize how Elder.js can know if an incremental build is in process so it can be exposed to plugins. Possibly this should be defined on the settings object that is available everwhere... but there isn't a clear way we can run the init() function across all plugins to make them aware of an incremental build without running init() twice or forcing plugins to move more of their logic into the bootstrap hook.
3. I'm a firm firm believer that plugin init() shouldn't be async as it blocks Elder.js from offering the server module. This may be refactor-able, but I want someone more than just me confirming this is a good design decision.

Other Things on My Radar

• Build Process optimization: The build process needs a bit of a refactor as it is really poorly written as I ripped out a dependency and used the native cluster module for Window's support and there is a lot of cruft there. During that refactor I want to move to a JIT queue so builds are truly optimal. The shuffleRequests flag works to speed up ElderGuide.com builds by about 30% where I believe a JIT queue could add another 15-20% speed gains. This can be done post v1. (Just tested Elder.js to build ElderGuide.com on a 24 core machine and got 18k pages with complex data queries built in 1 min and 21 seconds. I think with a JIT queue we can probably get builds under a minute.)
• A bare bones template: from experienced devs I've gotten a lot of great feedback that hooks are amazing and that the dataflow is pretty easy to follow. From beginners or people accustom to other libraries or Sapper, the feedback has been that the template is all too magical. I watched an intermediate js dev get exposure to Elder.js via a screenshare. After 30 minutes it 'clicked' but he was flailing as he tried to adapt other express or sapper concepts to Elder.js. There is a lot to be done to support user on-boarding specifically around data flow.
• After v1, I want to release a full blown blogging template. That use the markdown and images plugins.
• Possible removal or rework of how perf is exposed in data functions. At minimum it needs more documentation.

[swyxio]

to get an idea of how to reduce api surface area, here's an ideal i'd like to get to and we can maybe work backwards from there:

• have a folder full of markdown, say /blog or /docs
• install elder
• add elder to package.json start script, say elder serve blog and elder build blog

that's all the steps to have a useful, running site with default layout/navigation (this is also how elderjs becomes the default documentation tool for the svelte ecosystem). then we can customize everything else from there via a getting started/tutorial.

the principle i seek is "provide immediate value, let people customize later". Sara Viera got there for the single page Readme.md usecase. gatsby/nextjs/eleventy/docusuarus are all almost-but-not-quite-there. this is what i would have built for ssg had i continued working on it. i'd love to see something like it if you like the idea.

[nickreese]

@sw-yx I totally dig the idea, but I don't think a CLI supporting a specific usecase should live in the core. Instead what you outlined would be perfect for a template/plugin with a tiny CLI wrapper around Elder.js.

Here are my specific thoughts on the scope of Elder.js.

Elder.js Scope:

Before releasing Elder.js I sat down and asked myself if I could commit to maintaining it or facilitate it being maintained until 2023-2024 and doing so would result in a HELL YES for me.

Initially the decision wasn't a "Hell YES", but it became one for the following reasons:

1. As the Founder of ElderGuide The main business argument for ElderGuide.com spending limited development resources releasing and maintaining Elder.js was that long term it could be a great source of links to ElderGuide.com. In many ways this is an SEO experiment and it is the reason why the docs live on ElderGuide.com. If Elder.js gets support and links are built to ElderGuide.com this should help us long term with better rankings. It is definitely a bet and alone this wasn't enough of a usecase to open source the project.
2. As an investor who buys/builds SEO properties I realized that if I used Elder.js as the foundation for the investments, I could have predictability of how the sites are built (this is why it is an opinionated framework) even if different devs are working on different projects. Further, I also realized that long term each of these investments would have a business case to make sure Elder.js is maintained. This was the thought that made the decision a "HELL YES".
3. As both an investor/founder I realized that if Elder.js does take off, it would be much easier to hire and train developers and could open up the talent pool in ways that are hard to predict.
4. As a developer: For most of my career I've either written front end code or have been the CEO role. Neither of these roles lend themselves to good code review... lol. For this next stage in my life I want to increase my skills as a developer and I concluded that open sourcing this project will help me stay engaged, learn things I wouldn't have otherwise, and maybe make some friends along the way to keep JS interesting to me.

TL:DR; Guiding Elder.js' Scope

The scope of Elder.js will be limited to building a pluggable SSG/SSR framework for Svelte where all decisions are evaluated with SEO as the first priority.

The core of Elder.js will be a SSG and basic SSR framework. All other features and use-cases should be able to be implemented by the broader Elder.js community via hooks, plugins, or as a wrapper around Elder.js.

If the core of Elder.js isn't flexible to support said use-case, then it may be worth extending Elder.js' core to support that usecase.

This statement works because it clearly guides which of the different issues should be a part of the core such as:

• Serverless Elder rendering #28: possibly offer core support or changes to support the use-case.
• i18n support ?  #6: make sure this is doable in a plugin so that someone with a business case can maintain the codebase.
• Incremental builds #8: offer a blessed way, but don't do asset tracking which could be handled by a plugin.

Solving the Specific Usecase Outlined:

For the usecase outlined by @sw-yx, this could totally be done as a CLI wrapper around Elder.js/template.

Steps in more detail:

1. Users would clone your template that offered said CLI.
2. The CLI would make sure the folder with the .md files had a barebones route.js file specifying an all() function that returned an empty array (populated by the the plugin), a barebones permalink function, and you'd probably copy over a default Svelte template to match the route name.
3. The CLI could configure the markdown plugin in the user's elder.config.js with the route.
4. The CLI then would run a modified version of the build/serve steps show in the existing Elder.js template.

Bigger Picture

Overall I'd consider Elder.js a failure if it adds to JS fatigue, doesn't support the business cases above, or if I personally am not learning a ton. (this is my first OSS project where I am the lead dev)

It is weird to write my motivations in such a public forum, but hopefully understanding these motivations help inform what you can expect from me and Elder.js.

---

edit: clarified scope statement.

[nickreese]

Actively hacking on this here: #35

[nickreese]

@jbmoelker @sw-yx @halafi Major items besides elder.config.js and rollup.config.js are done here: #35

If anyone would like to try the template with shortcodes, it is here: https://github.com/Elderjs/template/tree/v0.2.0. Just a reminder that you'll need to clone the project.... not degit it.

[swyxio]

thanks nick - am focusing on shipping my site first and will upgrade to v0.2 after you launch!

[nickreese]

Hey everyone. This entire checklist has been crushed on #35 along with a bunch of other fixes if anyone would like to code review.

Going to be migrating over some plugins, getting things working on ElderGuide.com, and then we'll have a v1.0.0 on our hands. :)

[jbmoelker]

Wow! I got back from my vacation, and see that you already released v1! Amazing work!
@nickreese just wanted to congratulate you and the team. 🥇

Hope we can start using it in more projects at De Voorhoede. We have two projects using Elder in development. Hope to share them (including the code) soon.

[nickreese]

@jbmoelker Woot woot. :) Welcome back.

One thing I'd love another set of eyes on this implementation of module/nomodule #42.