ggranum / tangential-demo

Angular + Firebase bootstrap project and widget library, complete with authorization and analytics

Tangential

Live demo available here.

Angular, Firebase, Analytics, User Management, Advertising…​

Get it all in half an hour. Live, on the web. Half an hour.

One server - provided by Firebase. No AWS, no Google Cloud. One server, massively scalable, free for development and low-traffic sites.

Don’t want ads? Don’t care about analytics? Disable them during setup and save yourself 15 minutes - and you can add them at any time in the future.

In just a few minutes you can have your site hosted by Firebase Hosting at a project-specific URL. If you have your own domain, you can point it to Firebase Hosting and - once your DNS changes propagate! - you’re sorted. A fully bootstrapped web application, managed by you, backed by some of the best tools in the industry.

Features and highlights

Tangential is young. It is growing as we use it to build out our 'proof of concept' slash validation project, SnapLog.io, which is a fully featured, ad-supported, analytics-enabled, mobile-oriented 'Life Journal' application. SnapLog combines a purpose-driven form builder with long term tracking and correlation features (aka 'charts and graphs'), letting users track, for example, their mood and medication use, and correlate the two over time.

Tangential is already a great way to bootstrap your next personal project, or even something larger in scale. For small sites that need to deploy a single web site or web application, but don’t want to deal with hosting or implementing user management from scratch, you’ll have a hard time finding anything more powerful.

Below is a list of major features. Do note that many of the widgets and components you find in the Tangential demo are actually available as separate NPM packages. E.g. the Admin Console can be used without committing to using the entire bootstrap.

Firebase Hosted

Single server hosting. With Firebase Functions and some good Firebase Rule hygiene, you don’t need a separate authentication server. How nice is that?

Angular Goodness

Angular 4+, at the moment. We’ll keep the project dependencies up to date

Built in IAM console

View, create and assign new roles and permissions. (We revamped this feature area to use PrimeNg recently and are in the process of adding back the 'creation and assignment' functionality - soon!).

Themed

Customizable Material Design themes, using SCSS.

Logging

Log to the browser console - you can see the output in the demo if you open your console.

Google Analytics

Connect your Google Analytics account and get clean, easy to follow page and event tracking. don’t have an Analytics account yet? We’ll walk you through how to create one.

Google AdSense

We’re still creating ad widgets, but connecting AdSense is as easy as adding your AdSense campaign id to the environments.ts file. No idea what we mean? AdSense is Google’s ad serving service, and if you want to display ads in your web site or web app, we’ll walk you through how to get started.

AoT Compilation

There are things you can’t do if you want AoT to work in an Angular project. We don’t do those things, so your project can benefit from pre-compiled code.

Lazy Loaded Modules

If only administrators can access the Admin Console, shouldn’t it only load if the current visitor is an administrator? Exactly. We keep the landing page as small as possible.

Patterns and Practices

We strive to follow Angular recommendations, so that you pick up the best 'suggested practices' simply by borrowing from the Tangential code base. Where there’s an absence of suggested or standard practice, we strive for consistency and compile-time 'traceability' - the ability to prove at compile time that a thing is correct - for an example, take note of how we added traceability to our navigation targets.

Goals

Tangential exists to bootstrap new projects past the crufty nonsense that’s so important…​ and so boring. Some of that "nonsense" gets ignored in our desire to get real things out the door, just so we feel like we’re actually getting something useful done. Ever created a home page before you could authenticate users? Right. Wrote a page that couldn’t be internationalized, even though you know that you’ll be deploying across multiple languages?

To be clear, Tangential doesn’t have built in I18N yet. We’re working on it. Alas, we suffer from the fear of never deploying as well - perhaps worse than most, which is why we are building Tangential in the first place!

Aria, I18N and I10N are the 'only' remaining key features we wish to implement before targeting a 1.0.0 release. There is absolutely nothing preventing you from using the features provided by Angular to implement these yourself: Tangential does not, and will not, implement or encourage practices that prevent developers from using Angular the way it is meant to be used.

Real tools. Not toys.

Bootstraps and demonstration projects are notorious for taking shortcuts. We don’t. If you’re new to developing against a document oriented database you will find real code here, not another instant messaging client. Tangential tackles the real problems inherent in attempting to provide security and permissions-based access against real data. Decisions must be made regarding request counts versus permissions fidelity. Do I add a CAN_VIEW_USER_EMAIL permission, so that I can create a 'Demo Administrator' account? If we do, then we must also reorganize our data such that user email addresses are stored in the UserAuthData as a reference. If we don’t, then we’d have to request each field of the UserDocument in a separate request, or route the request through a Firebase Function.

Getting Started

For a detailed, step-by-step guide, see GETTING_STARTED.adoc.

High level overview - the experts guide

This is something of a checklist version, but it should give you an idea of how quickly you can set up and deploy a new Tangential project. It assumes you have a fairly robust set of development tools installed or aliased - see the detailed guide if one of these steps fails or doesn’t make sense!

1. Clone tangential-demo into your (future) project directory (use snake-case: e.g.g your-project-name): git clone https://github.com/ggranum/tangential.git

2. Optional: delete the .git directory, then re-init git and commit it to your own repository.

3. Go create two firebase projects here: Name them '${your-project-name}-dev' and '${your-project-name}-prod'.

   1. Take note of your Firebase Project Identifiers. These might differ from your project names.

   2. Enable email/password and anonymous authentication here. (Look at the URL, replace as needed)

   3. Download your private keys for both projects here.

   4. Copy the Firebase web app config from here into a scratch file. (The red 'Add Firebase to your web app' button).

4. Create an 'Account' with two 'Properties' in Google Analytics here (link will only work if you signed in and the primary account holder - it’s under the 'Admin' menu).

   1. Copy the Property Id Tokens into your scratch file - the two UA-00000000-X values.

5. Open a Terminal and cd to your project directory

   1. Run npm install.

   2. Run gulp project:init. This creates a number of files that are set as ignored in the .gitignore file.

      1. Open ./config/project.local.json and fill in the values from your scratch file.

      2. Still in project.local.json, provide valid email addresses for each of the default users. If you have a gmail account you can just find and replace 'example.com' with 'gmail.com', then find and replace 'example' with your own gmail email address - the '[e-mail]' is a Gmail trick that gives you unlimited mail addresses.

      3. You now have two empty firebase-adminsdk-private-key.local.json files in ./config/dev/ and ./config.prod, respectively. Paste the contents of your Firebase Private Key files that you downloaded earlier into these two files.

   3. Run gulp project;update-local

   4. Run gulp project:verify

   5. Run gulp firebase:push-project-users --dev (dev is default, but just to be explicit)

   6. Run gulp firebase:push-database-template --dev

   7. Run firebase use dev && firebase deploy (we use these commands in combination, because if you run firebase use prod and then forget to 'firebase use dev' before running deploy in the future, you could clobber prod. Don’t do it.)

6. Navigate to https://firebase-dev-project-id/firebaseapp.com

7. Start hacking in src/app to make the app yours!

   1. The first four files you’ll likely be interested in:

      1. ./src/index.html

      2. ./src/theme.scss

      3. ./src/app/main/main.component.ts

      4. ./src/app/features/casa/home/home.page.ts

You might want production deployed, too, right?

1. Probably you should commit all your new changes, test things out by running ng serve `ng serve --host 0.0.0.0 -p 4200 and such. Then:

   1. Run ng build --aot -prod -oh=all

   2. Run gulp firebase:push-project-users --prod

   3. Run gulp firebase:push-database-template --prod

   4. Run firebase use prod && firebase deploy

2. Navigate to https://firebase-prod-project-id/firebaseapp.com

   1. If you’ve set up Firebase Hosting to use your own domain, navigate there instead!

   2. Check out your site’s Analytics: https://analytics.google.com/analytics/web/?authuser=0#realtime/rt-overview/

Next Steps

We truly hope that this project helps gets you started. We are, of course, only barely scratching the surface of what you have just installed. We’ll be providing future blog posts and other documentation to help you make the most of the analytics tools, message bus, and other features that are built in to your new Tangential-based app.

Until then, if you’re new to Angular and/or Firebase, and you want to know more about how each Tangential feature set works, you can clone the main Tangential project and inspect the source, to get some ideas. Otherwise

What’s next for Tangential

We’ll be focusing on creating and improving the documentation for existing functionality, followed by improving that functionality itself (and rebuilding the test suite…​ sorry, we’re really providing a bad example here! It’s truly the highest priority, which will be performed in concert with improving the docs - it’s always nice when the docs match the expected behaviour, right?).

Sadly, unless we find additional funding, Tangential development is going to slow down significantly in the very near feature, as our lead developer (ok, ok, it’s obvious by the git commit logs: our only developer) is going to have to find a gig to pay the bills. You could of course help out by contributing, either code or resources.

Help us (me) help you (all)

Dispensing with the 'Royal We' for a moment…​

With this release, I am officially seeking both additional committers, and funds. It is, perhaps, early, but developing this project to this point has been incredibly rewarding. With no advertising or posts, I’m seeing a surprising amount of activity, both here on Github, and via the analytics for https://tangential-demo.firebaseapp.com/.

Creating this set of tools has been very rewarding, and I hope to make this my full time gig. I would vastly prefer to be able to do so without having to deal with Dual Licensing - not because it’s not worth what I will charge for it, but because I’m not shockingly greedy, and I truly enjoy knowing that my work has made other lives easier; that developers have managed to get more done than they otherwise would have, because of something I helped make.

If you stand to benefit from this work, I implore you to show me how valuable it is to you by contributing to the project on Patreon, or contacting me directly.

An open side note to Google: Considering how many Google technologies are in Tangential, and the income Google stands to earn if even one future million-user site chooses Firebase or Adsense because of Tangential, a sponsorship seems like some pretty affordable, advertising, no? :~)

Thanks

Thank you for your interest in Tangential. Don’t be shy about dropping questions or requests in the Issues.

Caio,