Lessons from writing my own

Angular utility lib

Context is important

• /mateusz-chrzonstowski
• /_mat3e_
• /mat3e
  • mat3e.github.io/talks/
    ll-angular/AngularWarsaw21.html
•  
• 🎓
• 🖥️ 💰 (2013)
• 👔 ⇒ 🏪
• 👪

Table of Contents

1. Why did I start?
2. DORF - Domain Object Reactive Forms
3. Lessons - Angular
4. Lessons - npm, webpack, other tools
5. "Marketing" and results

More context

Table of Contents

1. Why did I start?
2. DORF - Domain Object Reactive Forms
3. Lessons - Angular
4. Lessons - npm, webpack, other tools
5. "Marketing" and results

Ideas & motivation

• Dynamic Forms
  • Simplifying
  • Reducing the boilerplate
• No direct connection with any CSS framework
• A high level of abstraction
• Motivation
  1. Outer: To make dynamic forms easy for my colleague (involved in the side-project), without much professional experience
  2. Inner: To have an open-source project

Shock!

• An ordinary day at work vs. creativity
  • Come up with the name of the project
  • Come up with the slogan
  • Description, how-to examples
  • No pointless meetings :)
• Documentation?
  • API
  • License
  • Changelog

The name (1/2)

• Reactive/model-driven/dynamic forms
• DDD (Domain-Driven Design) - a great approach to software development, focus on Domains
• 

The name (2/2)

• DORF (German: village)
• 
• Test
• 

Open Source vs. Agile

• The latter development methods were explicitly designed for teams working in a single office, communicating face-to-face
• Open source developers have turned quality control into a science
• Another tenet of open source development (...) is full documentation
  • Agile? "working software over documentation"
• English has become the lingua franca practiced by all programmers
• Most open source projects involve end users in relatively old-fashioned ways, such as through alpha and beta releases

Building a lib? SOLID!

• SRP = "do one thing and do it well"
• OCP (Open/Closed Principle) = open for extension (configuration), closed for modification

  
                                  class StarRatingDefinition extends DorfFieldDefinition<number> { /*...*/ }
                                  class StarRatingMetadata extends DorfFieldMetadata<number, StarRatingDefinition> { /*...*/ }
                                  class StarRatingComponent extends AbstractDorfFieldComponent<number, StarRatingMetadata> { /*...*/ }
                              

• LSP (Liskov Substitution) = easy to switch from a class to its subclass
  • DORF - easy to switch between CSS frameworks :)
• ISP (Interface Segregation)
  • DORF field = definition, metadata, component...
• DIP (Dependency Inversion) = pluggability, loose coupling

Table of Contents

1. Why did I start?
2. DORF - Domain Object Reactive Forms
3. Lessons - Angular
4. Lessons - npm, webpack, other tools
5. "Marketing" and results

A game: 3 associations

@

Decorators

• Decorators are just specific functions
  • Well... what else in JS?

• 
                                  // @DorfForm()
                              
                                  export function DorfForm(options?: IDorfFormOptions) {
                                    return function <D extends Function>(targetConstructor: D) {
                                      Object
                                       .defineProperties(targetConstructor.prototype, { /* props */ });
                                    }
                                  }
                              

• 
                                  import { Input } from '@angular/core';
                              
                                  export function DorfObjectInput() {
                                    return function (targetProto: any, propName: string) {
                                      Input()(targetProto, propName);
                                      targetProto.dorfObjectInForm = propName;
                                    };
                                  }
                              

• Angular used to have @View and @Component

Components

• Focus on building blocks
• Abstract component classes, with decorators?
  • Yes, we can!

• 
                                  // @Component on the subclass
                                  export abstract class AbstractDorfFieldComponent<T, 
                                    M extends DorfFieldMetadata<T, IDorfFieldDefinition<T>>> {
                                      @Input()
                                      metadata: M;
                                      /* ... */
                                  }
                              

TypeScript

• API (understood as fields and methods)

• 
                                  export type InputType = 'color' | 'date' | 'datetime' | 'email' | /* ... */;
                                  
                                  export interface IDorfInputDefinition<T> extends IDorfFieldDefinition<T> {
                                      type: InputType;
                                  }
                              

• 
                                  setDomainObjValue: (val: DomObj[keyof DomObj]) => { obj[propertyName] = val; }
                              

• AoT compilation

  
                                  // order is defined as order?: number;
                                  get order(): number | undefined { return this.definition.order; }
                              

• TypeDoc - documentation generator

Table of Contents

1. Why did I start?
2. DORF - Domain Object Reactive Forms
3. Lessons - Angular
4. Lessons - npm, webpack, other tools
5. "Marketing" and results

Webpack, karma

• Angular CLI hides a lot
• My idea: dorf/config
  • karma
  • ts
  • webpack
• package.json

  
                                  "test": "karma start config/karma/conf.js"
                              

• config/karma/conf.js

  
                                  webpackConfig = require('../webpack/tests')
                              

GitHub

• CI? - Travis!
  • Signing in with GitHub
  • Adding a predefined build script
• Badge? Shields.io + markdown
• A webpage? E.g. master branch + docs folder
• README
  • Badges at the top
  • A quick win/a short example
  • Examples, examples, examples (the online ones)
  • Links to the documentation, articles

Node, npm

• README - different display than on GitHub
• .npmignore (by default equal to .gitignore)
  • dist and .d.ts files shouldn't be ignored
  • .ts files should be
• Many downloads right after publishing a new version
• Frequent updates = better position in search results
• Semantic versioning (Major.Minor.Patch)
  • Backward compatibility (e.g. DorfModule, DorfCoreModule)

Table of Contents

1. Why did I start?
2. DORF - Domain Object Reactive Forms
3. Lessons - Angular
4. Lessons - npm, webpack, other tools
5. "Marketing" and results

Promotion

• Twitter, proper hashtags (max. 2 per post)
• Medium - articles demonstrating a library
• Pluralsight - comments under the video about Reactive Forms in Angular
• StackOverflow - answering under Angular reactive/model-driven/dynamic forms questions

Getting a user/user needs

Results

• 7 GitHub stars (my first stars ever)
• +1000 downloads in a single day (29.08.2017)
• 300-400 downloads a month (before Angular 5)
• +100 downloads a month currently
• Huge knowledge/awareness growth
  • The authors of a library/framework are the software developers, not superheroes
  • New approach, different priorities
  • Great understanding of the framework (especially of its narrow part)