TL;DR ExpressJS & VueJS Web App Cookbook, Customisable CRUD Library, CI/CD, Cloud Container Deployment, Web Components, ES Modules, Vite
Latest Version 0.4.4 - Released 2020 Nov 27 2230 +8GMT
- Frontend Examples
- Vite, Vue3 & mwc, vaadin: Web Components, Leaflet Map, ECharts, Webcam, Signature canvas, PWA, CRUD frontend for CRUD backend
- SPA, Vue2 & Vuetify: Websockets, Graphql (subscriptions, cache, optimistic UI, refetch queries), REST, VueCrudX, i18n, RxJS, 2FA login, Github social login, recaptcha, JWT refresh token, GA OTP
- Vanilla JS, ES Modules, Vue3 & bulma: No bundler, scalable VueJS Application, example codes (signed uploads, JWT refresh token, OTP)
- Express JS Backend
- Cors, proxy middleware, helmet, error handling, logging, OpenAPI
- Objection ORM, Knex, MongoDb, Relational DB data example, migration, seed, GraphQL, Redis
- Webpush & 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, token in HttpOnly cookies, GA OTP, role, Passport SAML
- Unit Test & Integration Test
- Development & Deployment
- Github Actions - Manual Trigger
- Docker setup of mongodb with replica set, mysql, saml IDP, kafka
- MongoDB of mongodb with replica set, mysql, saml IDP, kafka
- Mysql
- Saml IDP
- hashicorp vault & secrets
- Documentation: always work in progress and to be improved
Docker is required to test
- mongodb
- saml
- hashicorp vault
- kafka
# clone repo and install backend
git clone https://github.com/ais-one/vue-crud-x.git
cd vue-crud-x
npm run install
# install the required common-lib JS scripts
npm run update
# 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 mac
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/*.inv,js files not present. So there maybe some console log errors (but it is ok to ignore), graphql and websockets will not work. Quick start is still usable. Use the README.md to fill up
Visit 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 (click on link to view nobundle app or link to view vite production build app)
See above
cd example-spa
npm i
npm run serve
Navigate to http://127.0.0.1:8080/spa 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
For Push Notification
- using Google FCM, setup your firebase account and messaging, also setup FCM server key in backend
- using self hosted webpush is also supported and available
cd example-vite
npm i
npm run dev
Navigate to http://127.0.0.1:8080/vite to view application
Login is same as SPA
You can test PWA Push notifications using Webpush or FCM () on Dashboard page depending on .env. file configuration (need to be on 127.0.0.1).
Click the following buttons in order (see their output in console.log and screen):
- sub PN (subscribe)
- Test PN (send a test message to user id 1 - on sqlite)
- Unsub PN (unsubscribe)
cd example-vite
npm run build
example-app should be running
Navigate to http://127.0.0.1:3000/vite/
From vue-crud-x folder
cd example-spa
npm run build
example-app should be running
Navigate to http://127.0.0.1:3000/spa/
- potential slow rendering by server app, added complexity in code, rehydration errors, added complexity in server
- nuxt/nuxt#8102
- prefer static sites and lazy loaded SPA
Refer to link below on how to try out...
- https://github.com/ais-one/vue-crud-x/blob/develop/docker-devenv/saml/docker-compose.yml
- You can test out on the example-vite Signin UI, clicking on SAML button to see redirect callback
Codes are use in...
- https://github.com/ais-one/vue-crud-x/blob/develop/example-app/app.js
- https://github.com/ais-one/vue-crud-x/blob/develop/example-app/lib/express/saml.js
- https://github.com/ais-one/vue-crud-x/blob/develop/example-app/router/saml.js
To run unit & integration test on /api/authors. E2E testing is Work In Progress
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 mac
Command 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 mac
Command to simulate process triggered by cron (NOTE: may be better to use cron to call API than trigger a process)
npm run process-cron # windows
npm run process-cron:unix # linux or mac
- example-app for backend example
- example-app/lib/esm for common ESM codes to be used by express applications
- example-app/lib/<all_others> for common CJS codes to be used by express applications
-
example-nobundler for vanillaJS frontend example
-
example-vite for Vite Vue3 frontend example
- example-vite/lib/rollup for common codes to be used by Vite Vue 3 (should have same contents as example-app/lib/esm)
- example-spa for Webpack Vue2 frontend example
- example-spa/lib/webpacked for common codes to be used by Webpacked Vue 2 applications
- common-lib/esm for common javascript libraries using ES Modules
- In package.json Files
- Set environment using config.env property (development, uat, staging, production)
{
"config": {
"env": "development",
}
}
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
If too many config properties, split it to other more and files
vue-crud-x
+- .circleci/ : not used
+- .github/ : github related CICD and automations
+- common-lib/ : common libraries
| +- esm/ : es modules
+- docker-devenv/ : docker for development environment
+- docs/ : documentation
+- example-app/ : example backend - See example-app/README.md for Project Structure
+- example-nobundle/ : frontend associated to backend (Vue3 no bundle) - See example-nobundle/README.md for Project Structure
+- example-spa/ : frontend associated to the backend (Vue2 webpack) - See example-spa/README.md for Project Structure
| +- lib/webpacked/ : webpacked components for frontend (e.g. VueCrudX.vue)
+- example-vite/ : frontend associated to backend - (Vue3 rollup) - See example-vite/README.md for Project Structure
| +- lib/esm-rollup/ : rolled up components for frontend (e.g. apollo.js)
+- k8s/ : kubernetes YAML files (WIP)
+- .editorconfig
+- .gitignore
+- BACKLOG.md
+- CHANGELOG.md
+- LICENCE
+- package.json
+- README.md
+- rest-cmd.http : rest commands for testing
Using github actions
Manually triggered deployment on .github/workflows/manual.yml
selectable inputs
- environment (uat for now, development does not deploy anything)
- application (example-app, example-vite)
- code branch
NOTE config/secret contents will not be in repo for CI/CD (so you can get errors), those should be put in VAULT
current secrets
- GCP_PROJECT_ID
- GCP_SA_KEY
- VAULT_uat, passed in as VAULT
# do not merge
VAULT="unused"
# connect to a hashicorp vault and obtain secrets to merge
VAULT={ url, token } # base64 encoded
# pass in secrets, this way is insecure and not a good way to send in secrets
VAULT={ secrets: { ... all your secrets here } } # base64 encoded
- Project roadmap at BACKLOG.md
- Release notes at CHANGELOG.md
- Current Issues at CHANGELOG.md
- Main documentation starts at docs/home.md
- vue-crud-x library documentation can be found in docs/VueCrudX.md
- Deployment notes can be found in (docs/deployment/home.md)
- Custom Element docs/custom-element.md
- Kafka docs/kafka.md and code found in example-app/sandbox
- TCP Server docs/tcp.md and code found in example-app/sandbox
- v0.4+ Improve folders and structure organization, handle CI/CD better
- 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