Welcome to Viage.js
Please go to the Viage Website for a web version of the documentation and tutorial
It is 2019
According to various Web stats, less than 5% of all web traffic is IE, and its market share is shrinking fast. This leaves about 95% of the world using modern up-to-date browsers. Current browsers have some really nice DOM APIs that are easy to use and standard across the big 4 (Chrome, Edge, Firefox, and Safari). Modern browsers now support ES6 features like Classes, Promises, etc... Add with great tools like Typescript and Webpack, why do we need giant frameworks again?
React and Angular
While React and Angular solve a lot of problems and are amazing, I still find myself having issues:
When I work with React, I find that JSX and the virtual DOM get in my way. I end up adding DIV elements that act as containers so the JSX compiler is happy. There are limits on what you can do with inline styling, and things that were easy, such as styling buttons, are now harder. Getting data out of a form, means I have add handlers to each field so that when the data changes, I can keep track of it. Because I am interacting with a virtual DOM, I can't just ask the form elements for their values. Because everything is passed down through components, including callbacks to notify the parents of changes, I often find that changing functionality requires changes in the entire parent child chain.
When I work with Angular, I find that its complexity is high. Because you have to use a lot of HTML directives in your HTML, there is a learning curve for yet another part of this large framework. The HTML template directives are hard to debug because you can't step into them. Passing data in and out of a component should be trivial and its not. Adding a module usually requires me to modify code in several files and almost every bit of standard functionality has a new and different Angular counterpart. For instance, adding a click handler should be as close to the DOM APIs as possible but instead you use:
A Better Way?
So is there a better way that relies on existing DOM and JS functionality?
That is exactly the question I am trying to answer. If I just use some reasonable practices and modern features, do these large frameworks really buy me anything? Here are the design principles I am using in this project:
- Use only Modern Web APIs that are standard across the big 4 browsers
- Take advantage of JS / TS modern language features
- Keep everything as simple as possible while still maintaining easy development
- Take advantage of offline tools such as NPM, Webpack, and Typescript
- Minimize the amount of learning required
- Keep everything component based
So what is Viage?
Viage is simply 4 very tiny classes, some design design best practices, and a CLI. The CLI takes care of setting up skeleton projects. It configures Typescript and Webpack so all you have to do is start writing code.
Is Viage fast?
It turns out that a lot of time and effort goes into making browsers fast with the native APIs. Using them produces good results. To verify this I implemented a Viage version of the React Fiber Demo. It is as least as fast as React Fiber. You can see for yourself at Viage Sierpinksi Demo
Is Viage small?
To test this I created a shopping list app in Angular, React, and Viage. The total code sizes generated for each framework are shown below:
You can see that Viage in this test case is 8-18 times smaller!
For the sake of codes size and complexity comparisons, I have implemented this same app in React and Angular. I tried to keep the code as similar as possible within the bounds of each framework. You can find them and a running Viage version at the links below:
Is Viage easy?
I think so. If you compare the React, Angular, and the Viage versions of the Shopping List App. You will see that a similar amount of code had to be written for each framework. Viage's classes and API are small. Viage relies on standard web technologies whenever possible and minimizes re-invention. It is my opinion that the Viage version of the Shopping List App wins at being the smallest and easiest to understand.
What are the advantages of Viage?
- Viage is fast and small
- Viage is very compatible with existing libraries
- Viage relies on standard web technologies that are already well documented and well maintained
- A side effect of this is that Viage has a low complexity and is minimal
- Viage is easy to learn
- Open a terminal or command line prompt and change directory to your projects directory
- If you haven't already installed the Viage CLI:
npm install -g viage-cli
- Now create an empty project that will output a 'Hello From Viage' Page. You can use any project name but this example uses hello-world-viage
viage app hello-world-viage cd hello-world-viage
- This will create an empty project that is all configured and ready to go. To run it type:
npm run start
- You should see a development server start and a browser window open with a message that says: 'Hello From Viage'
- npm run start - Builds and launches a Development Webserver
- npm run build - Builds the project in release and outputs it to dist/
- npm run build-embedded - Builds the project in release and outputs it to dist/ and embeds the bundle.js into the HTML
- npm run test - Launches ts-jest and runs all the Jest tests that are in the tests folder
- npm run serve - Launches an express server to serve the contents of the dist folder. This allows testing of a release build
- viage app <project-name> - creates a skeleton project
- viage component <component-name> - creates a new component and adds it to the project
- viage service <service-name> - creates a new service and adds it to the project
How To Viage
Components and Services
There are three basic types of Viage objects, Components and Services, and a special object called a Router.
Components contain HTML and other components. Components communicate down stream by calling functions directly in their children much like React does. Sometimes a parent needs to know that something changed in a child component. That can be done by emitting and event, supporting a callback API between parent and child, and notification via a Service.
Services are singletons that are usually a data repository. They should handle the setting and getting of data and provide a mechanism to notify everyone else when the data has changed. The Service base class has some helpers for adding listeners and dispatching events.
Viage also has a quick and dirty router that is about 225 lines of code. This is a configurable Router and can be a HASH, STANDALONE, and LOCATION router. It allows Single Page Apllications to be created quickly and easily. The Router maps routes to components which render into a common element in the DOM. For more information see the API Docs and Router Design Considerations.
Shopping List Tutorial
The quickest way to learn Viage is to walk through a simple shopping list app. You can find it at Shopping List Tutorial
When using the Viage CLI to create a new project, it creates all the hooks necessary to start writing tests with ts-jest right out of the box. ts-jest is a Tyepscript version of Jest. All you have to do is add your tests to the test directory. The file name must have .test in it somewhere. To run tests type:
npm run test
For examples checkout the tests in the Shopping List Tutorial. There is plenty of great documentation at the Jest website for info on how to Jest.
The Viage API is documented is on the Viage Website
For general information on how to do things like add a linter, vist it the FAQ