ReVector
Live demo available here.
About
This project uses Angular2, Firebase, and @ngrx to create 'reactive' style modules that can be dropped into projects that make use of similar features.
The flagship module is the Authentication & Authorization Module - AKA User Management. Check it out here
Visual components are (or will be) consumable without needing to include functionality. For example, using the asciidoctor-panel component in your project will not introduce a dependency on Firebase or NgRx. The sign-in-panel needs to be separated into two modules before it can be imported without adding dependencies beyond Angular2. This work is planned, but not available yet.
As a template for component-library projects
This projectβs build system was adopted from the Material Design teams Material2 project, from prior to their merging all their components into a single namespace. Aside from offering a number of useful components, you may find this project to be a useful template to follow if you are attempting to create a component library of your own.
Getting Started
If you are interested is using this project as a template for your own component library, check out the DEVELOPER.md readme.
For developing with the components in this library, take a look at the Revector Demo project to see how to import, configure and consume Revector components.
Each component has itβs own readme file, which should (eventually) contain the required install steps specific to that component.
If you have not started your project yet we very much recommend using the Angular-CLI to create your project, then follow the Revector Demo steps to to get going. Weβre working on a step-by-step, 'getting started from zero' document and hope to make it available it soon. For the time being, there are the docs below, and the Revector Demo, which should be enough if you have some experience with Angular2!
Install all the things
Install any of the components you wish to use. Be sure to check the dependencies of the components you do install if you chose not to install them all.
npm install --save @revector/admin-ui
npm install --save @revector/asciidoctor-panel
npm install --save @revector/auth-service
npm install --save @revector/drawer
npm install --save @revector/shared
npm install --save @revector/sign-in-componentAll components require Angular2. Some also require NgRx and firebase. If you donβt have all that installed, do take a look at RevectorDemo/project.json to get the most up to date copy of all the dependencies and their versions.
Global Tools
There are a handful of tools that are usually installed globally included in the devDependencies of the Revector Demo. Global NPM installs should be discouraged, as keeping versions in sync is a pain. It is better to create aliases to locally installed versions of tool libraries, or reference them via scripts in the package.json file. We realize this opinion is not universal, but experience leads us to prefer the use of aliases over global installs.
To create aliases for the tools used by this project, execute the following:
echo source ~/.bash_aliases >> ~/.bashrc
echo alias firebase="./node_modules/.bin/firebase" >> ~/.bash_aliases
echo alias ng="./node_modules/.bin/ng" >> ~/.bash_aliases
source ~/.bash_aliasesThe use of a bash_aliases file is optional, but often calling source on ~/.bashrc repeatedly isnβt completely side effect free (e.g. path becoming very, very, very long), and who has the energy to fix that?
The above use of aliases does restrict the use of these tools to the base directory of active projects. In practice this is rarely a problem.
This can also be solved via NPM scripts, which are provided in the package.json for the Revector Demo project. To call ng serve via the script you need to instead call the npm script weβve provided (see 'scripts' in package.json):
npm run ng -- serveNote the -- before serve. This is how you pass arguments to an NPM script.
Generally speaking, adding an alias is more developer friendly. But when thatβs not possible npm scripts are there to fall back on.
Firebase Components
The 'fully functional' components (e.g. Auth) require a Firebase backend.
Create and configure your firebase project
The backend is provided by Firebase. So youβll need a firebase project. Create one here: https://console.firebase.google.com/.
You may want to find and replace '${YourProject}' in this document with the identity of your new project. If you are using WebStorm, set search options to 'Ignore case', and set 'Preserve Case' to true and you can take care of it all in one go.
Once youβve created the project, open it to the overview page (if it wasnβt opened for you: https://console.firebase.google.com/project/${yourproject}/overview) and click 'Add Firebase to your web app'. Youβll be given a popup that contains your Firebase configuration.
You will also need to enable email/password authentication. Do so here: https://console.firebase.google.com/project/${YourProject}/authentication/providers
Firebase API Configuration: environment.local.ts
The following assumes you have a .gitignore line that ignores *.local.* files. You do NOT want to commit the following information into a public repository.
Navigate to './src/environments' and create a new file named 'environment.local.ts'. Paste your firebase credentials in so the file looks like the following:
export const noCommitEnvironment = {
firebaseConfig: {
apiKey: "your-key",
authDomain: "${yourproject}",
databaseURL: "https://${yourproject}.firebaseio.com",
storageBucket: "${yourproject}.appspot.com",
messagingSenderId: "yourSenderId"
}
};Initialize your Firebase project
Right now you have no data stored in your firebase project (NOTE if this is not the case, make backups or go start a new project!). The User Management console has a bit of a boot-strap issue, as you need certain permissions in order to assign permissions to Userβsβ¦β but if you donβt have any userβs with those rightsβ¦β Exactly. So we will bypass the ReVector-Demo admin panel for this first bit of configuration. Which WILL DELETE ALL YOUR EXISTING CONTENT.
The Firebase CLI
One of the 3rd party tools installed by NPM is the Firebase CLI tool. We added an alias for it above. Weβre going to use it here to push our initial data into our firebase project directly. But first you need to update the .firebaserc file with the name of your firebase project.
First, list your firebase projects:
> firebase listYouβll probably be told to login. And once you do (and re-run 'list') youβll get something that looks like this:
ββββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββ¬ββββββββββββββ
β Name β Project ID / Instance β Permissions β
ββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββΌββββββββββββββ€
β ReVectorDemo (current) β revectordemo β Owner β
ββββββββββββββββββββββββββ΄βββββββββββββββββββββββββββββ΄ββββββββββββββNow open .firebaserc and replace 'revectordemo' with the Project ID of your project.
With that done, we should now be ready to push our initial data:
> firebase database:update "/" ./src/environments/database.init.jsonWe could have used either push or set, but chose update to reduce the risk of frying you existing data for those readers who may rush through docs without reading carefully :~)
Building and deploying: Production
If you donβt use Angular2-CLI, you will need to modify the various ng * commands to match your own build tools versions thereof.
Weβre going straight to the production build first, then weβll walk back to the development builds. This is partly to be certain that the production build works before you change any code. A lot of the supporting tools, such as Angular 2 and the Angular CLI, are only recently starting to settle down into stable libraries, so breakage is quite possible.
To deploy your project to Firebase hosting we just need to run two commands:
> ng build -prod
> firebase deployMagic, no?
Building and deploying: Development
There are two development builds that will watch your code for changes by default. Well, two that we use. You can read up on the Angular CLI for more details if you wish (hint: you should probably do this eventually - itβs really very powerful and it will save you a TONNE of time creating new components and routes!)
ng serve
When youβre working on UI widgets, youβll probably want this build:
> ng serveIt starts builds your project and starts a server, then watches for changes. It includes live-reload, so your browser will update in the background each time the build completes (which is to say, after each change you make).
ng test
For editing service oriented code, ng test is where itβs at:
> ng testBuilds your code and runs your unit tests (using Karma). Rebuilds on changes and runs the tests again. Does development get any better?
Contributing
Weβd love your bug reports, fixes, widgets, ideas. Take a look at 'DEVELOPER.MD' to get started hacking on the project, or add an issue.
Running unit tests
ng testRunning end-to-end tests
Work in progress.
