Design Concept: JAMstack

[arcticicestudio]

This epic documents the design concept of Nord Doc's web development architecture and serves as a plan for the initial launch.
It defines the process steps of the three key criteria.

🚧 This is a living document which means it is work in progress, not completed yet and will be extended!

What is the JAMstack?

JAMstack: noun \’jam-stak’
Modern web development architecture based on client-side JavaScript, reusable APIs, and prebuilt Markup.

It is not about specific technologies, but a new way of building websites and apps that delivers better performance, higher security, lower cost of scaling, and a better developer experience.

A project is built with the JAMstack if it meets the three key criteria JavaScript, APIs and Markup:

Any dynamic programming during the request/response cycle is handled by JavaScript, running entirely on the client. This could be any frontend framework, library, or even vanilla JavaScript.

All server-side processes or database actions are abstracted into reusable APIs, accessed over HTTPS with JavaScript. These can be custom-built or leverage third-party services.

Templated markup should be prebuilt at deploy time, usually using a site generator for content sites, or a build tool for web apps.

For detailed information check out the official website that provides information about how projects can adapt to it, best practices, examples, resources and a great community.

JavaScript

Implementation issues: #25

Any dynamic programming during the request/response cycle is handled by JavaScript, running entirely on the client. This could be any frontend framework, library, or even vanilla JavaScript.

We 💙 React!

All web related projects we've developed are built with React and we're not alone. React is not just a trend, it's more like a new standard how the web is built. It revolutionized the way to think about the components a website is made of and how to compose and orchestrate them to form a fluid running unit. It's finally a new way to solve the complicated topic of state handling and the most performant technique to update only necessary parts of the DOM without the large overhead to re-render it completely every time.

React describes itself as…

• Declarative - painless to create interactive UIs and design simple views for each state in applications where React will efficiently update and render just the right components when the data changes. Declarative views makes code more predictable and easier to debug.
• Component-Based - Build encapsulated components that manage their own state, then compose them to make complex UIs and since component logic is written in JavaScript instead of templates, it is easy to pass rich data through the app and keep state out of the DOM.
• Learn Once, Write Anywhere - React doesn’t make assumptions about the rest of the technology stack, so developing new features in React without rewriting existing code can be done easily.

Next to this React can also render on the server using Node and power mobile apps using React Native.

There are so many more arguments and we think all most every developer heard or read about it so this little summary here is only a small introduction.
If you like to get to know more about React your first touchpoint should be the official website and their extensive and absolute fantastic docs, tutorials and blog. They are maintained and well-written by the React core team itself and the contributors from one of the largest open source community. They are made with a flat learning curve in mind to be very beginner-friendly but at the same time are the main source for every advanced and experienced React developer. They increase the degree of knowledge up to deep-dives into the heart of React and include many great articles about best practices, how to increase the performance and maintainability of apps, the latest features and updates from the React ecosystem, tips & tricks of the core team and many more.

Nord Docs will be built with the currently latest stable version 16.6 and will update and adapt to upcoming features like e.g. Hooks and Async Rendering when they become stable to always enhance the project and code base.

All implementation details and requirements are documented and tracked in the corresponding issues:

• React #33 - “React”

APIs

Implementation issues: #25

The plan is to make use of the official GitHub GraphQL API (v4) to get data about all Nord projects which can then be used to e.g. show the actual count of stars, the latest release version, interact with issues and pull requests and many more. There are also GitHub Apps that allow to work and interact with the projects.

More APIs might be added later on for many more flexible data fetching using the awesome GraphQL API provided by Gatsby (implemented in #25).

Markup

Implementation issues: #25

This criteria is the actual content of a website.
Gatsby (#25) allows to use Markdown for it. This comes with the nice side effect that the already existing documentations can simply be adapted and reused, but unfortunately it is limited to it's reduced and simplified syntax.

To use the great power of React this project will make use of the MDX specification, a new language and abstract syntax tree definition.

In order to ensure a vibrant ecosystem and community, tooling needs to exist for formatting, linting, and plugins. This tooling requires a foundational specification and abstract syntax tree so that parsing is properly handled before transforming to JSX/Hyperscript/React/etc and potentially leveraging existing plugin ecosystems.

We will use the official implementation, the fully-featured MDX parser, loader and JSX renderer to allow to seamlessly use JSX in Markdown documents by importing components and export metadata or any other ECMAScript compliant data structures like frontmatter.

• 💻 Everything is a component: Use existing components inside your MDX and import other MDX files as plain components.
• 🔧 Customizable: Decide which component is rendered for each Markdown element ({ h1: MyHeading }).
• 📚 Markdown-based: The simplicity and elegance of Markdown remains, you interleave JSX only when you want to.
• 🔥 Blazingly blazing fast: MDX has no runtime, all compilation occurs during the build stage.

More details are provided through the official website that includes docs to get started, usage examples and advanced configuration and customization information.