Note: Nodewood is still in development, so this documentation may change at any time.
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
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 to simplify and speed up the design of your app. Tailwind's utility-first workflow 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. Vue.js is lightweight, in on-page size, execution speed, and cognitive overhead. There are only a few key principles to learn before you can dive right in and happily work with the majority of the framework.
Nodewood's API is built with Express, 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
# 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 four folders:
ansiblefolder contains an Ansible project that can be used to build a development VM or deploy to a production server. This follows a traditional Ansible project layout.
appfolder is where your application code will live. More on how this is organized later.
woodfolder is where the base Nodewood code lives. More on how this is organized later.
wwwfolder is for your marketing site. This is shipped empty, as you may want to use a static site generator, WordPress, etc.
wood folders are near-mirrors of each other:
apicontains 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
configis where your application configuration lives. Secrets are not kept in this folder.
featuresis where the majority of your code will live.
libis used to contain common library code that will be used for both your frontend and backend, but are not part of any specific feature.
migrationsis where your database migrations will be stored.
uicontains 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
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 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:
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.