Introduction
Cookbook Rule #1 - Do Not Build Up Technical Debt
As developers we create different applications. Along the way, we come up with code recipes for ORMs, GraphQL, SSO, charts, OpenAPI, Vue/React SPA, etc.
These recipes solve real world problems and can be reused elsewhere!
The Evergreen Cookbook Project
The project originally began life as a CRUD Component.
As more and more functionality and codes were added, the code "recipes" were consolidated in a "Cookbook" for future use.
If you just want to dive in, visit the project.
1 - IMPORTANT - Read Me First!
The templates (express and vuejs template) and libraries (shareable libraries and tools) projects referenced in the Recipes are based on the two principles below.
1.1 - Updateable Templates
Your project is created using a template. If template updates, can upstream changes be merged with minimal impact on userland codes?
Yes and it is achieved through:
- Design
- Create folder where all userland code is placed, template must NOT touch this folder
- template should not to be part of a monorepo
- Process
- clone template and create remote called
upstreampointing to template - update framework when necessary by merging
upstreamintoorigin
- clone template and create remote called
1.2 - Manageable Sharing
You have code shared between multiple projects and libraries. If the code is updated, is breaking dependents and dependencies avoidable?
Yes, based on the following principles:
- Shared libraries should be isolated and versioned. Use last-known-good version and update when ready
- …
Considerations
The recipes must be continuously maintained:
- adding new recipes and removing obsolete ones
- updating and improving existing recipes (e.g. cleaner code)
We also should bear in mind the following which have impact on cookbook users:
- make it easy for users to build and maintain multiple projects based on the cookbook
- make it easy for users to update their projects when cookbook recipes are updated
- easy to deploy using CI/CD, containers
Recipes
Some available recipes in the cookbook are:
- GraphQL & subscriptions
- SAML2, OpenID Connect, OAuth social logins, JWT, refresh token, 2FA/TOTP
- Multi-part forms, file uploads, signup uploads
- REST, OpenAPI documentation and validation
- Web components - Webcam, Canvas inputs, CRUD table
- MongoDB, replication, transactions, streams
- SQL Query Builders, migration, seed
- cors, body parser, helmet, connect-api-history-fallback
- Automated testing
- Visualization (Charts, Maps, etc.)
- Logging
Find out how each recipe works by checking out, building, and running the code while referencing the project documents.
Cookbook Web Frontend Type
There are 3 ways to build a web frontend application
- Single Page Application (SPA)
- Server-Side Rendered (SSR)
- Static Sites
The table below shows the comparison between the 3 ways.
After comparing the feature of each way, the decision was to focus on SPA and Static Sites.
Some Historical Notes
- A CRUD component was developed in late 2017 due to a desire to create a better table editor using VueJS 2 and Vuetify 1.
- A backend project and authentication was added as this was needed. Features and applications start getting added, updated, removed.
- Vuetify 2 (3Q 2019) introduced breaking changes. Hence the need to look at more stable or reduced number of dependencies.
- Backend structure was re-organized to allow same codebase on multiple projects.
- Project was again re-organized when docker and CI/CD had to be taken into account.
- With ES Modules introduced, a no bundler version of the frontend was created. The CRUD UI was also migrated to a use Web Components and Bulma CSS.
- Docker compose files for applications such as DB, Redis, Kafka, Vault were added to support local development.
- Vue3 broke Vue2 plugins, fortunately the project did not use many plugins (it used libraries like leafletJS directly instead). The migration was quite painless.
- Escaped much pain when VueJS and its 3rd party libraries update, e.g.:
- vee-validate v1 -> v2 -> v3 -> v4 (keeps breaking)
- vue-apollo (cannot use for Vue3 yet)
- vue-rx (cannot use for Vue3 yet)
- vuetify v1 -> v2 -> v3 (keeps breaking)
- Experience with a sister project helped in addressing cookbook user considerations stated above.
- Now awaiting npm workspaces in the upcoming NodeJS 16 LTS release... and focus on project stability.
Hope you find the cookbook project, and its recipes helpful.
The cookbook is continuously being updated and improved to remain relevant and useful.
We are looking for contributors and maintainers to continuously make it better.
Thank you for taking your time to read this.
Top comments (5)
it was so easy to build+run an example on previous version (0.2.x), that i get bored after one hour to try to run same example (the one with book, authors and categories) with latest version, than i just gave up. i'm precisely interested by the generic and customizable table with vuejs so if you could help, i would appreciate
"Run the following steps to clone, install and run" - this is not enough!
Can you more explain the prerequisites?
Hi,
Sorry give me a few days, There is some work being done on develop branch and I will merge it to master.
I am cleaning up the structure and documentation... the coming update is attempt on ease of re-use of both frontend and backend common components... so...
One can use it to build multiple applications with different business use cases.
That would be great. I was able to log in using Firebase login but then wasnt sure what I am suppose to do next.... I am not sure how to set up any of the dbs (like how do I configure it to use PostgreSQL, MongoDB, etc? and am I suppose to run Redis? Maybe best thing would be to put this in a Docker file and have everything ready to go?
Hi...
Documentation and update is still in progress. Please ignore the Firebase and Mongo Stitch part. The project aim is to have components that are not locked into a single vendor.
For local only install, it will use SQLite as the database. Nothing needs to be installed except Node & NPM.
I am working on deployments also, Docker, Kubernetes, Google App Engine... this is one of the missing pieces in the puzzle...