Elder.js: An Opinionated, SEO focused, Svelte Framework.

Star

Elder.js is an opinionated static site generator and web framework built with SEO in mind. (Supports SSR and Static Site Generation.)

Features:

• Build hooks allow you to plug into any part of entire page generation process and customize as needed.
• A Highly Optimized Build Process: that will span as many CPU cores as you can throw at it to make building your site as fast as possible. For reference Elder.js easily generates a data intensive 18,000 page site in 8 minutes using a budget 4 core VM.
• Svelte Everywhere: Use Svelte for your SSR templates and with partial hydration on the client for tiny html/bundle sizes.
• Straightforward Data Flow: By simply associating a data function in your route.js, you have complete control over how you fetch, prepare, and manipulate data before sending it to your Svelte template. Anything you can do in Node.js, you can do to fetch your data. Multiple data sources, no problem.
• Community Plugins: Easily extend what your Elder.js site can do by adding prebuilt plugins to your site.
• Shortcodes: Future proof your content, whether it lives in a CMS or in static files using smart placeholders.
• 0KB JS: Defaults to 0KB of JS if your page doesn't need JS.
• Partial Hydration: Unlike most frameworks, Elder.js lets you hydrate just the parts of the client that need to be interactive allowing you to dramatically reduce your payloads while still having full control over component lazy-loading, preloading, and eager-loading.

Context

Elder.js is the result of our team's work to build this site (ElderGuide.com) and was purpose built to solve the unique challenges of building flagship SEO sites with 10-100k+ pages.

Elder Guide Co-Founder Nick Reese has built or managed 5 major SEO properties over the past 14 years. After leading the transition of several complex sites to static site generators he loved the benefits of the JAM stack, but wished there was a better solution for complex, data intensive, projects. Elder.js is his vision for how static site generators can become viable for sites of all sizes regardless of the number of pages or how complex the data being presented is.

We hope you find this project useful whether you're building a small personal blog or a flagship SEO site that impacts millions of users.

Project Status: Stable

Elder.js is stable and production ready.

It is being used on on this site and 2 other flagship SEO properties that are managed by the maintainers of this project.

We believe Elder.js has reached a level of maturity where we have achieved the majority of the vision we had for the project when we set out to build a static site generator.

Our goal is to keep the hookInterface, plugin interface, and general structure of the project as static as possible.

This is a lot of words to say we’re not looking to ship a bunch if breaking changes any time soon, but will be shipping bug fixes and incremental changes that are mostly “under the hood.”

As September 2020, the ElderGuide.com team expects to maintain this project at least until 2023-2024. For a clearer vision of what we mean by this and what to expect from the maintainers as far as what is considered "in scope" and what isn't, please see this comment.

Getting Started:

The quickest way to get started is to get started with the Elder.js template using degit:

Here is a demo of the template: https://elderjs.netlify.app/

Step 1: Clone Template

npx degit Elderjs/template elderjs-app
cd elderjs-app

Step 2: Install Dependencies

npm install # or just yarn

Step 3: Start the Project

npm start

Navigate to http://localhost:3000. You should see your app running.

Developing using the Template:

For development, we recommend running two separate terminals. One for the server and the other for rollup.

Terminal 1: Server

npm run dev:server # `npm start` above starts a server, but doesn't rebuild your Svelte components on change.

Terminal 2: Rollup

npm run dev:rollup # This rebuilds your svelte components on change.

Once you have these two terminals open, edit a component file in src, save it, and reload the page to see your changes.

To Build/Serve HTML:

npm run build

Let the build finish.

npx sirv-cli public

Routes

At the core of any site are it's "routes" or templates.

In Elder.js a route is made up of 2 files that live in your route folder: ./src/routes/${routeName}/ folder.

They are:

1. A route.js file. This is where you define route details such as the route’s permalink function, all function and data function.
2. A Svelte component to be used as a template matches the ${routeName}. eg: ./src/routes/blog/Blog.svelte (from here on out we refer to these specific Svelte components as "Svelte Templates")

Route.js

route.js files are required to have an all function, a permalink function, and an optional data function.

Here is what a route for a website's homepage might look like it's simplest form.

// ./src/routes/home/route.js
module.exports = {
  // template: 'Home.svelte' is assumed if not defined. (note: capitalized first letter.)
  // layout: 'Layout.svelte' is assumed if not defined.
  all: async () => [!span!], // an array of request objects. A slug is required for each.
  permalink: ({ request, settings }) => request.slug, // a sync function that turns request objects into relative urls.
  data: async ({ query, request, data }) => {
  // do magic to get data from your data store.
  const externalData = await query.db(`SELECT * FROM city WHERE slug = $1`, [!request!])
  // const externalData = await query.fetch(`https://yourdata.com/api/city/${request.slug}`)
  return {
    ...data,
    // ...externalData
  }
};

Three things are happening here:

• all(): The all function returns an array of all of the "request" objects for a given route. Since this is the homepage, it returns an array with a single request object of {slug: '/'}.
• permalink(): The permalink function transforms request objects into permalinks. In this example, the "permalink" for {slug: '/'} is /. This makes sense because "/" is the relative url of the homepage of a site.
• data(): The data function takes the data passed in and returns a new data object with data fetched for this specific route. (This is optional)

NOTE: A route's permalink function must be synchronous.

all() Function

Here is the function signature for a route.js all function:

all: async ({ settings, query, data, helpers }): Array<Object> => {
  // settings: this describes the Elder.js settings at initialization.
  // query: an empty object that is usually populated on the 'bootstrap' hook with a database connection or api connection. This is sharable throughout all hooks and functions.
  // data: any data set on the 'bootstrap' hook.
  return Array<Object>;
}

permalink() Function

Here is the function signature for a route.js permalink function:

permalink: ({ request, settings }): String => {
  // NOTE: permalink must be sync. Async is not supported.

  // request: this is the object received from the all() function. Generally we recommend passing a 'slug' parameter but you can use any naming you want.
  // settings: this describes the Elder.js bootstrap settings.
  return String;
};

data() Function

Whether you’re building a personal blog or complex data driven SEO site, a route's data function is the recommend place to fetch (from a db, api, or other source) and prepare data to be consumed by your Svelte templates.

Here is the function signature for a route.js data function:

data: async ({
  data,
  query,
  helpers,
  settings,
  request,
  errors,
  perf,
  allRequests,
}): Object => {
  // data is any data set from plugins or hooks. Make sure that the object that is returned extends the data object.
  return Object;
};

Here is what a common data function may look like:

module.exports = async ({ query, settings, request, data }) => {
  // do magic to get data from your data store.
  const externalData = await query.db(`SELECT * FROM city WHERE slug = $1`, [!br!]);
  // or
  // const externalData = await query.api.get(`https://yourdata.com/api/city/${request.slug}`)...
  return {
    ...data,
    ...externalData,
  };
};

In short we're taking the request object returned from a route's all function and hitting an external data store.

It's important to note that we're also merging this external data with the data passed into the data function so we are picking up any data set by hooks or plugins.

How Routing Differs from Express-like Frameworks

Together the all and permalink functions are used to complete map of all of the urls a specific route should handle.

If you are familiar with express or polka then you are likely familiar with defining your routes as /blog/:id/ where :id is a parameter that is passed in a route.

While this type of routing is familiar to many in the JS community, it has some distinct limitations when building a static site generator. Specifically:

1. When generating your static site, 'crawl' all of the links of a site to generate a complete map of urls.
2. Complex logic or regex is needed to have /senior-living/:nursingHomeId/ and /senior-living/:blogId/.
3. It assumes that all parameters needed to generate a page can be determined by the URL.

Inverted Routing

To solve the issues inherent with express-like routing, Elder.js uses what we refer to as an "inverted router" to build a map of all available pages.

How this works, is that for each route Elder.js:

1. Compiles all of the request objects by running the route's all function.
2. The request objects are then passed to the permalink function to generate URLs.

Once it has gathered all of the permalinks, Elder.js now has a complete map of every page it should build or handle SSR for.

This approach was chosen to give the user complete control of their URL structure instead of being bound by the limitations of being able to determine a route solely by a URL.

Route.js Best Practices:

With the simple example out of the way, let's talk about best practices and let's look at a more complex example of a route.js file.

Best Practice: A route's all function should return the minimum viable data points needed generate a page.

Skinny request objects. Fat data functions.

When people first encounter Elder.js there is a strong temptation to load the request objects returned by a route's all function with tons of data.

While this approach works it doesn't scale very well. Fetching, preparing, and processing data should be done in your data function.

That said, it is recommend that you only include the bare minimum required by your database, api, or data store and then organize the rest of the data fetching, preparing, and organization in the route's data function.

Real World Example

To drive this point home and to show a more complex example of routing, imagine you're building a travel site that lists tourist attractions for major cities throughout the world.

You have a city route and for each page on that route you need 3 data points to query your API, database, or datastore in order to pull in all of the rest of the page's data.

These data points are:

1. The language of the page being generated
2. The City slug
3. The Country slug

Here is what your route.js would look like to support /en/spain/barcelona/ and /es/espana/barcelona/.

// ./src/routes/city/route.js
module.exports = {
  all: async ({ query }) => {
    // await query.db(`your implementation here`) or await query.api(`get data`);
    return [!br!/]