TL;DR ExpressJS & VueJS Web App Cookbook, Customisable CRUD Library, CI/CD, Cloud Container Deployment, Web Components, ES Modules
Latest Version 0.3.3 - Released 2020 Aug 23 0315 +8GMT
- Frontend Examples
- NEW Vite & Vue3: Web Components, Leaflet Map, ECharts, CRUD frontend for CRUD backend
- SPA & Vuetify: Websockets, Graphql (subscriptions, cache, optimistic UI, refetch queries), REST, VueCrudX, i18n, RxJS, 2FA login, Github social login, recaptcha, JWT refresh token, GA OTP, Webcam (WIP), Signature canvas (WIP)
- PWA: FCM push notification & PWA features
- SSR using Nuxt: Handling 500 and 404 errors, show gotchas of SSR
- Vanilla JS, ES Modules: No bundler, scalable VueJS Application , example codes (signed uploads, JWT refresh token, OTP)
- Express JS Backend & Common Libs
- Cors, proxy middleware, helmet, error handling, logging, OpenAPI
- Objection ORM, Knex, MongoDb, Relational DB data example, migration, seed, GraphQL, Redis
- FCM push notification, Sendgrid email, Nexmo SMS, Telegram
- AgendaJS message queue
- File uploads, Signed URL file upload to GCP Storage
- Websockets, graphql
- JWT using RSA, JWT refresh token, Passwort SAML (WIP), token in HttpOnly cookies, GA OTP, role
- Unit Test & Integration Test
- Development & Deployment
- Docker setup of mongodb with replica set
- Documentation: always work in progress and to be improved
- Deploy script to VM, GCP Cloud Run, GCP Storage (for SPA & static sites)
# clone repo and install backend
git clone https://github.com/ais-one/vue-crud-x.git
cd vue-crud-x
npm run install
# create and seed relational db on SQLite
npm run knex # windows
npm run knex:unix # linux or mac
# create and seed MongoDB requires MongoDB - you can skip this but MongoDB examples will not work
npm run mongo # windows
npm run mongo:unix # linux or mac
# run the backend
npm run app # windows
npm run app:unix # linux or macVisit the following URLs
- http://127.0.0.1:3000/api/healthcheck - app is running normally
- http://127.0.0.1:3000/api-docs - OpenAPI UI
- http://127.0.0.1:3000 - Website served by Express with functional samples and demos at
NOTES
- MongoDB examples needs MongoDB to work. To resolve, chose one of the methods to install MongoDB in docs/mongodb/install.md
- The example-app/config/secret folder is missing so there maybe some console log errors (but it is ok to ignore), graphql and websockets will not work. Quick start is still usable. To resolve, in example-app/config folder, rename sample-secret folder to secret. You can look at the readme inside sample-secret folder for more information
- The code below is important, calls setup and reading of configs. It is used in example-app/index.js and also used in example-app/process-long.js (long running process) and example-app/process-cron.js
// index.js
require(require('path').join(process.cwd(), 'common-lib', 'setup')) // first thing to setup
require(LIB_PATH + '/config') // first thing to include from LIB_PATHcd example-web/spa
npm i
npm run serveNavigate to http://127.0.0.1:8080 to view application with VueCrudX demo
Login using the following:
- User: test
- Password: test
- OTP (if enabled - e.g. USE_OTP=TEST): use 111111 as otp pin
MongoDB required for testing CRUD table to work
cd example-web/vite
npm i
npm run devNavigate to http://127.0.0.1:8080 to view application. Just click login button
For Push Notification to work, setup your firebase account and messaging, also setup FCM server key in backend
cd example-web/pwa
npm i
npm run servecd example-web/ssr
npm i
npm run devNotes
- for static content see example-web/ssr/README.md on generating and serving static content
- Static sites have the same advantages as SSR but are less complex to set up. The only thing to take care of is redirection of unknown dynamic routes
- We use SSR mode, WITHOUT implementing the server side features for efficient debugging of static generated sites.
E2E testing is Work In Progress
To run unit & integration test on /api/authors route.
TO TEST EVERYTHING PLEASE change describe.only(...) to describe(...) in the test scripts in example-app/tests
npm run test # windows
npm run test:unix # linux or macCommand to run long process (do take note of caveats, for production need a monitor to handle restart strategy)
npm run process-long # windows
npm run process-long:unix # linux or macCommand to simulate process triggered by cron (NOTE: it may be better to use cron to call API rather than trigger a process)
npm run process-cron # windows
npm run process-cron:unix # linux or macFrom vue-crud-x folder
cd example-app/web/spa
npm run buildChange the example-app/config/index.js file contents
//...
WEB_STATIC: [
//...
{ folder: process.cwd() + '/spa/dist', url: '/' }, // UNCOMMENT this line
// { folder: APP_PATH + '/public/demo-express', url: '/' }, // COMMENT this line
//...
]
//...mkdir <my-project>
cd <my-project>
git clone --depth=1 --branch=develop https://github.com/ais-one/vue-crud-x.git
# copy required files
cp vue-crud-x/deploy.sh vue-crud-x/update.sh vue-crud-x/package.json vue-crud-x/.eslintrc.json vue-crud-x/.gitignore .
# copy required folders
mv vue-crud-x/common-lib .
# copy docker related files
cp vue-crud-x/.dockerignore vue-crud-x/Dockerfile vue-crud-x/docker-compose.yml .
# copy the example-app for use as reference (optional)
mv vue-crud-x/example-app .
# copy the example-web for use as reference (optional)
mv vue-crud-x/example-web .
# cleanup
rm -rf vue-crud-x- In package.json
- Set application name in config.app property (indicate folder of your application - set to example-app if using example-app folder)
- Set web name in config.web property (indicate folder of your application - set to example-web if using example-web folder)
- Set environment using config.env property (development, uat, staging, production)
- In update.sh
- Uncomment the lines, this script is used to update the common library when needed
{
"config": {
"env": "development",
"app": "example-app",
"web": "example-web"
}
}The example-app/config/ folder contains the config information.
You can override the configurations using <NODE_ENV>.env.js files, e.g. development.env.js or uat.env.js in example-app/config/secret
If too many config properties, split it to other more and files
See script update.sh
The project structure is shown below
vue-crud-x
+- common-lib/ : common components
| +- auth/ : for express authentication
| +- comms/ : messging
| +- esm/ : JS that can be used by both front and backend
| +- express/ : express related
| +- services/ : nodejs libs
| +- webpacked/ : webpacked components for frontend (including vue-crud-x)
| | +- dist/ : distribution folder for CRUD component
| +- app.js : the express app boilerplate
| +- config.js: the base config
| +- setup.js: setup globals
+- docker-devenv/ : docker for development environment (e.g. run redis, mongodb from here)
| +- mongodb
+- docs/ : documentation
+- example-app : an example backend application **Use this example for your project**
| +- config/ : centralized config folder
| | +- certs/ : certificates for HTTPS and JWT signing
| | +- k8s/ : kubernetes YAML files (WIP)
| | +- secret
| | | +- .env.<node_env>
| | | +- <node_env>.deploy
| | | +- <node_env>.pem
| | | +- <node_env>.gcp.json
| | | +- <node_env>.gcp.cors.json
| | +- index.js : home to your configs, can scale by adding folders and files
| +- controllers/
| +- coverage/ (auto-generated by test runner)
| +- db/
| | +- migrations/
| | +- mongo/
| | +- seeds/
| +- graphql/ : graphql stuff
| +- jobs/ : message queue jobs
| +- logs/
| +- middlewares/
| +- models/
| +- public/ : for serving static files - website
| | +- demo-express/ (127.0.0.1/)
| | +- demo-nobundler/
| +- router/
| +- tests/ : Jest tests
| +- uploads/ : for serving static files - files
| +- ecosystem.config.js
| +- index.js
| +- jest.config.js: JEST testing
| +- knexfile.js: Knex query builder
| +- package.json
| +- process-long.js: sample long running process
| +- process-cron.js: sample cron triggered process
| +- README.md
+- example-web/ : frontend associated to the application
| +- pwa/
| +- spa/
| +- ssr/
| +- vite/
| +- <your other front end here>
+- sandbox/ : Useful scripts
+- .dockerignore
+- .eslintrc.json
+- .gitignore
+- deploy.sh
+- docker-compose.yml
+- Dockerfile
+- LICENCE
+- package.json
+- README.md
+- RELEASE.md
+- update.sh
vue-crud-x library documentation can be found in docs/VueCrudX.md
Roadmap and Release notes for the library and examples can be found in Release.md
Deployment notes can be found in (docs/deployment/home.md)
Documentation can be found starting at docs/home.md
vue-crud-x 0.2+ Article
- v0.3+ Reorganize folders and structure, for ease of developing and maintaining multiple applications.
- v0.2+ uses Vuetify 2. Due to many breaking changes from Vuetify 1 to 2, CRUD component code was refactored to be more UI framework agnostic (reduce dependencies!), easier to use, improving code quality, documentation and supprting article - VueJS+ExpressJS CRUD & Cookbook
- v0.1 and Vuetify 1 will be supported under the v1 branch. You can refer to the v1 Legacy Article (For Historical Reference)
- recaptcha
- filter
- pagination
- custom form slot
- tags and lazy-load autocomplete
- click button to child table
- inline edit
- date-picker, select and other controls