generator-angular-module
Yeoman Generator for AngularJS module builder (aimed at making Bower components with Github Pages for the demo(s)). Based off of Brian Ford's excellent post on AngularJS modules with Bower.
Getting Started
Install Yeoman Yo, Bower, & Grunt if you haven't already:
$ npm install -g yo bower grunt-cli
Install this generator:
$ npm install -g generator-angular-module
NOTE: Before creating a new module, CHECK / SEARCH to see if one already exists! And check the name on Bower since you must create one with a UNIQUE name.
- Bower Components - make sure to search for multiple keywords (i.e. 'angular-form' and 'angular-input' and 'angular form' and 'angular input' since the search isn't great since it depends on keywords and not all components are well listed).
- Angular (NG) Modules
- Google it!
Finally, naviagate to a (new) directory where you want to create your AngularJS module and initiate the generator:
$ yo angular-module
Next Steps
After you've followed the Yeoman prompts and your project has been scaffolded out for you, you'll have TWO Git branches, master
(where the final bower component code will live) and gh-pages
(where the development and demo takes place). You'll start in the gh-pages
branch - use the files created for you to actually build your module and a demo (which you'll use to manually test as you're building).
- install
- run
npm install && bower install
- this installs grunt and any dependencies such as AngularJS
- run
- write code! (actually build your module and confirm it's working with the demo)
- check the
app.js
staticPath
variable - this assumes anangular-directives
folder off the root of your server but just set that path to be relative to your server root for the demo to work locally. - NOTE: since Github Pages does NOT have a backend accessible, you'll need a server running to serve
index.html
for you (i.e. for a WAMP server with root in thewww
folder, if your code is inwww/angular-directives/angular-module-test
, typehttp://localhost/angular-directives/angular-module-test
in a browser and your demo page should come up). TODO
text is placed in files for places for you to write code / change things- put your demo code in
pages/home
(home.html
andHomeCtrl.js
) - you can also create additional pages/routes as well (i.e. one page per demo - ideally demo different configurations and examples/options) - run
grunt
to build yourmain.css
file and any other build files
- check the
- create github repo
- go to github.com and create a new repository (that matches the name you typed in the Yeoman prompt earlier)
- commit & push
gh-pages
branch- open
app.js
and uncomment the secondstaticPath
line that has agh-pages
comment in it so it will work on gh-pages git commit
your changes to thegh-pages
branch and push it to your new Github repository, to thegh-pages
branch (i.e.git push origin gh-pages
)- NOTE: it may be better to push the
gh-pages
branch AFTER pushing master since whichever is pushed first to Github will be the default branch (though you can change this with the settings for the repo on Github) - you want themaster
branch to be the default on Github.
- NOTE: it may be better to push the
- open
- make, commit, tag, & push
master
branch- copy over / get your core module files (i.e. for a directive, your
angular-module-test.js
andangular-module-test.less
files as well as theangular-module-test.min.js
file that Grunt generates for you) fromgh-pages
with the commandgit checkout gh-pages angular-module-test.js angular-module-test.min.js angular-module-test.less
(replaceangular-module-test
with your module name). - update the
README.md
file and any other files for the core bower module (bower.json
andCHANGELOG.md
should already be ready for v1.0.0 but may need to update these) - Git commit and then TAG your master branch (i.e.
git tag v1.0.0
) then push to Github withgit push origin master --tags
- make sure to push your tags since that's how Bower does versions!
- copy over / get your core module files (i.e. for a directive, your
- (optional) Register your new bower component! I.e.
bower register angular-module-test [github repo location]
- Note: don't pollute the bower repository - sharing is great and encouraged BUT make sure you're confident in the quality of your module and are ready to (actively) maintain it before publicly registering it; people can STILL use your component WITHOUT being publicly registered by downloading it straight from Github so register with care and only as needed!
You're done! You now have a bower component for an AngularJS module (directive or service) with one or more demos on Github!
More info: Again, see Brian Ford's excellent post on AngularJS modules with Bower, where this was inspired from.
Getting To Know Yeoman
What is Yeoman?
Trick question. It's not a thing. It's this guy:
Basically, he wears a top hat, lives in your computer, and waits for you to tell him what kind of application you wish to create.
Not every new computer comes with a Yeoman pre-installed. He lives in the npm package repository. You only have to ask for him once, then he packs up and moves into your hard drive. Make sure you clean up, he likes new and shiny things.
Yeoman Generators
Yeoman travels light. He didn't pack any generators when he moved in. You can think of a generator like a plug-in. You get to choose what type of application you wish to create, such as a Backbone application or even a Chrome extension.
Yeoman has a heart of gold. He's a person with feelings and opinions, but he's very easy to work with. If you think he's too opinionated, he can be easily convinced.
If you'd like to get to know Yeoman better and meet some of his friends, Grunt and Bower, check out the complete Getting Started Guide.