# Overview

Nodewood is a JavaScript SaaS Starter Kit, designed to save you weeks or months of time when launching your next SaaS app. Similar to a general-purpose framework, Nodewood provides you with a collection of starter code that you can start customizing with your own business logic. However, the starter code that Nodewood provides is targeted towards SaaS apps specifically, and provides features like user auth/management, an app template and admin panel, subscriptions, etc. Compared to hiring someone to write all that code for you, you could save significant time and money in the race to launch your SaaS app.

Interested? Sign up to learn when we launch and get a 10% discount!

Note: Nodewood is still in development, so this documentation may change at any time.

# Philosophy

Nodewood is a pretty opinionated product, and understanding the philosophy behind those opinions will help you understand if Nodewood is right for you, and will improve your experience using Nodewood.

# Emphasis on shared code between front-end and back-end

Commonly, you will need to run the same code in both your UI and API. If you use different server and client languages, you have to write the same code twice, and maintain both implementations over time. Nodewood uses Javascript for the front-end and back-end, which means you can write validation, calculation, composition, or any other shared code once and use it everywhere.

In addition, Nodewood implements the following patterns to simplify code re-use:

  • Nodewood comes with a common pattern for form validation that can be used to validate forms in the UI before the user submits them and also on the server to validate API requests.
  • Nodewood models contain no database access functionality, and are closer to an Entity object in Domain-driven design. This means they can safely contain common calculation and composition functions.

# Designed for simplicity

Nodewood relies on Tailwind CSS (opens new window) to simplify and speed up the design of your app. Tailwind's utility-first workflow (opens new window) makes it easy to rapidly create a consistent, responsive, good-looking application without having to learn an entire CSS framework.

Nodewood's UI front-end is build using Vue.js (opens new window). Vue.js is lightweight, in on-page size, execution speed, and cognitive overhead. There are only a few key principles (opens new window) to learn before you can dive right in and happily work with the majority of the framework.

Nodewood's API is built with Express (opens new window), which prides itself on being "minimal and flexible". Nodewood makes it easy to write controllers to express common routing patterns, provides services for database & email access, and then gets out of the way.

# Feature-based development

We no longer keep our HTML, JavaScript, and CSS in separate folders just because they have different file extensions, the world has moved on to component-based design (opens new window). So why keep all your Controllers together just because they're controllers? Nodewood uses "features", folders that co-locate all the API, UI, and shared code related to a specific feature of your app. This way, code is "closer" to related code, and is easier to find and work with.

# Easily-available source and per-file overrides

The Nodewood framework installs into a wood folder instead of as an NPM library, which means you can always easily reference how a certain page is built or how and API endpoint works, etc. More-importantly, your app folder is a mirror of the wood folder, and if you want to override a file from the wood folder, all you need to do is create one in the same location under app. From there you can inherit the original or start from scratch. This allows you to take advantage of the power of Nodewood out of the box, but easily extend or replace that functionality when you need to.

# Important Concepts

Nodewood has a few important concepts you'll need to learn to develop quickly and effectively. Spending a little time reading the following will make a lot of other things make a lot more sense.

# Directory layout

At the root of your project, you'll find three folders:

  • The app folder is where your application code will live. More on how this is organized later.
  • The wood folder is where the base Nodewood code lives. More on how this is organized later.
  • The www folder is for your marketing site. This is shipped empty, as you may want to use a static site generator, WordPress, etc.

The app and wood folders are near-mirrors of each other:

  • api contains code explicitly for the backend of your service. This folder won't contain too many files, since most code will be part of a feature, and thus contained in the features folder.
  • config is where your application configuration lives. Secrets are not kept in this folder.
  • features is where the majority of your code will live.
  • lib is used to contain common library code that will be used for both your frontend and backend, but are not part of any specific feature.
  • migrations is where your database migrations will be stored.
  • ui contains code explicitly for the frontend of your service. This folder won't contain too many files, since most code will be part of a feature, and thus contained in the features folder.

The wood folder also contains one extra folder - docs. While you can choose to document your API (or not) as you like, Nodewood comes with this folder already populated for you to reference existing Nodewood API endpoints.

# Per-file overrides

Nodewood takes inspiration from the HMVC pattern (opens new window) when providing a pattern for you to extend from. When you start up a fresh application, most of the code for that application lives in the wood folder. In order to allow you to override those default files, Nodewood has a modified file requirement strategy:

Any require or import file that starts with # will attempt to find the file in the app folder first, and failing that, will look in the wood folder afterwards.

This means that in order to override a file in the wood folder, all you need to do is place a file in the same location in the app folder. If the file you are replacing is a Controller, you can extend the Nodewood class and add your own functions to it. If it's a Vue component, you may need to copy the original file and modify it, or replace it entirely with one of your design.

This makes it very simple to extend the basic application provided for you without having to go in and modify any Nodewood files directly. You never need to touch anything inside the wood folder, and in fact you shouldn't, as future upgrades will replaces files in that folder without telling you.