From 3ff62702a20c6cf09aa922376020906aff1f700d Mon Sep 17 00:00:00 2001 From: Geoff Doty Date: Sun, 2 Dec 2018 02:21:35 -0500 Subject: [PATCH] additional documentation --- CONTRIBUTING.md | 71 +++++++++++++++++++++++++++ README.md | 112 ++++++++++++++++++++++++++++++------------- docs/dependencies.md | 38 +++++++++++++++ docs/riotjs.md | 0 gulpfile.js | 2 +- 5 files changed, 188 insertions(+), 35 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 docs/dependencies.md delete mode 100644 docs/riotjs.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..570e4b4 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,71 @@ +# Contributing + +So you want to contribute, awesome. **Thank you**. + +Bug reports and code and documentation patches are all welcome. You can help this project also by using the development version and by reporting any bugs you might encounter. + +You may contribute in several ways like: + +* Creating new features +* Fixing bugs +* Improving documentation and examples +* Translating any document here to your language + +## Table of contents + +* [Contributing](#contributing) + * [Developing](#developing) + * [Running tests](#running-tests) + * [Reporting a bug](#reporting-a-bug) + * [Request a feature](#request-a-feature) + * [Commit message](#commit-message) + * [Code style](#code-style) + +## Developing + +For now, check out the read me and any documentation located in the `docs/` folder. + +> This should be expanded in the future, [want to help?](http://code.negative9.net/geoff/riot-starter/issues/new) + +## Running tests + +Running tests *should* be as easy as: + +```bash +npm run test +``` + +> no client-side testing solution exists yet, [want to help?](http://code.negative9.net/geoff/riot-starter/issues/new) + +## Reporting a bug + +Use the [issue tracker](http://code.negative9.net/geoff/riot-starter/issues/new) to report any bug you find. +Bugs description should include: + +* How to reproduce the bug; +* Easy to understand title; + +Would be nice to have some code showing how to reproduce the code, you may use [gist](https://gist.github.com) or [Codepen](https://codepen.io) for uploading your example code. + +## Request a feature + +Use the [issue tracker](http://code.negative9.net/geoff/riot-starter/issues/new) to request a new feature. + +Keep in mind, this is for the minimalist. Something that can be easly integrated into any project. + +## Commit message + +Commit messages should includes issue reference and a imperative easy to understand sentence. + +## Coding style + +If it is supported in all major browers without transpiling, then please use those JavaScript language features in your code, with one caveat -- readablity is king. + +Currently all ES5 and ES6/ES2015 are available. + +This project is linted agaist [ESLint](https://eslint.org/) and the [`.eslintrc.json`](.eslintrc.json) is dead-simple, and all you need to followed. + +Thank you for reading this. + + +Hey, **star** this *repo* and/or share it with your friends. \ No newline at end of file diff --git a/README.md b/README.md index f1be7ea..8b8c8ba 100644 --- a/README.md +++ b/README.md @@ -1,83 +1,127 @@ # RiotJS App Starter -> A Rapid Application Starter kit for RiotJS +> A Rapid Application Starter kit for RiotJS minimalists -Rapidly prototype your next single-page application, with a `zero-build` out-of-the-box web-component solution. Need to go beyond the prototype stage, fret not, the tools are in-place to take you to production. +Rapidly prototype your next single-page application, with a `zero-build` out-of-the-box web-component solution using [RiotJS](https://riot.js.org/) for the fastest way to iterate over UI for development -- **bar-none**. -This is built as simple as possible, but no simplier +No crazy syntax, just HTML, CSS and JavaScript. -### Features +No isolated eco-system, work with any library, any tool, any way you want! -- `RiotJS` 3.x - - `Web Components` for reuseable UI - - `Events` for communication - - `Route` for url navigation -- `HTML5Boilerplate` 6.x static file base -- `ESLint` for coding style -- `Gulp` for production builds +[RiotJS](https://riot.js.org/) is tiny; tiny foot print, tiny API, and this leads it to be extremely fast to learn -- closest to web standards as you can get. -### Requirements +What are you waiting for -- **GO FORTH AND BUILD YOUR APP, RAPIDLY!** -[NodeJS](https://nodejs.org/) is used to install `vendor/` dependencies and a method to `build` your project for production via `gulp` +*Designed to be as simple as possible, but no simpler* -## Getting Started +## Features -1. Run `npm install` to load vendor dependencies +- [RiotJS](https://riot.js.org/) 3.x give us the core UI building blocks + - `Web Components` for composable and reusable UI + - `Events` to communicate between components or other code +- [Riot-Route](https://riot.js.org/api/route/) the simplest way to manage URL navigation +- [Grayscale](http://n2geoff.github.io/grayscale/) Small, 2kb gzipped CSS framework with a layout focus +- [Gulp](https://gulpjs.com/) is there for when your ready for *production*. See [Build for Production](#build production) below -2. Start coding in `src/public` +**Requirements** -3. run the `public/index.html` from your favorite web server\* +- [NodeJS](https://nodejs.org/) -> \* try `live-server` from `npm` or via [Visual Studio Code]() plug-in +> Installs `vendor/` dependencies and `npm build` to get your project into production ## Why Zero-Build? **SPEED!** -A production pipe-line should *NOT* be in your way while developing... +A production pipe-line should *NOT* be in your way while **developing**. You should be able to iterate over your designs *FAST* , see those changes *FAST*, and when your ready, you should be able to build your solution *FAST* , but only as the final step -- not every step. -...however, `npm build` is there when you need it +`npm build` is still there. See Below. -## How +### How -`RiotJS` is blazing fast, outside of a production build, this project uses the `runtime-compiler` that can easily handle thousands of tags/actions in hundreds of milliseconds. +[RiotJS]() [client-size compiler](https://riot.js.org/online-compiler/) is blazing fast, it only adds about 10kb, and it can easily handle thousands of tags/actions in hundreds of milliseconds. -### Build +## Getting Started -When you are ready to move to production you can run `npm build`. This will create a `dist` folder with all your optimized assets, web-components, vendor dependencies and remove the riot `runtime-compiler` to shave off another 100kb +1. Run `npm install`, this will install all vendor dependencies -Check out the [gulpfile]('gulpfile.js') for all the build options if you do not want to build everything. Every task is commented, and split-up so you can grep it easily. +2. Start coding in `src/public` -## Project Structure +3. run the `public/index.html` from your favorite web server\* + +> \* try `live-server` from `npm` or via [Visual Studio Code]() plug-in it's awesome! + +### Project Structure ``` -docs/ <-- additional documentation src/ - public/ <-- development is done here + public/ <-- develop here css/ <-- your css files js/ <-- your javascript files + app.js <-- basic routing/utils bootstrap images/ <-- your images tags/ <-- web-components vendor/ <-- vendor dependencies, ie code you did not write index.html <-- start here ... <-- web meta files +docs/ <-- additional documentation test/ <-- tests (one day) gulpfile.js <-- task runner README.md -... <-- project meta files +... <-- misc project meta files ``` -## Polyfills +### Web Components -Todays "Evergreens" browsers support 99% of `ES6`, providing a pethra of capabilities, such as `import`, `class`, `fetch`, and `promise`. Depending on your desired browser support, you may find a polyfill to suit your needs... +Web-components are just `HTML` files wrapped in a custom `tag`, which means they can be as simple as + +```html + + + +``` + +These files are usually saved as `my-component.tag`, but to get proper syntax highlighting the *norm* is keep them as HTML files naming them something like `my-componet.tag.html` + +> Save in the `tags/` folder, organize this however you like + +Of course we want our component to do more, so... + +...*for now*, go check out the [RiotJS GuideI](https://riot.js.org/guide/) + + +## Build for Production + +When you are ready to move to production you can run `npm build`. This will create a `dist` folder with all your optimized assets, web-components, vendor dependencies and remove the riot `runtime-compiler` to shave off another 100kb + +Check out the [gulpfile]('gulpfile.js') for all the build options if you do not want to build everything. Every task is commented, and split-up so you can grep it easily. -...but such is beyond the scope of *this* starter kit. ## Testing - TBD + +## Additional Documentation + +- [How Dependencies are Used]('docs/dependencies.md') + + ## TODO -- integrate Jasmine for tests -- bring in ajax lib (n2geoff/riot-http) for non-es6 environments? +- Include a testing framework [Jasmine](https://jasmine.github.io/), [test.it](https://github.com/n2geoff/testit), or? +- Is good AJAX support the missing ingredient? or is`fetch` good enough? - add routing example + +## Support + +Please open [an issue](http://code.negative9.net/geoff/riot-starter/issues/new) for support. + +## Contributing + +Anyone is welcome to contribute, however, if you decide to get involved, please take a moment to review the [guidelines](CONTRIBUTING.md), there minimalistic;) + +## License + +[MIT](LICENSE) diff --git a/docs/dependencies.md b/docs/dependencies.md new file mode 100644 index 0000000..31ea512 --- /dev/null +++ b/docs/dependencies.md @@ -0,0 +1,38 @@ +# Frontend Dependencies + +I've always been hesitant using NodeJS for client-side dependency managment, but the `npm` package [frontend-dependencies](https://github.com/msurdi/frontend-dependencies) takes that away, and I did not want to commit any external vendor code here. + +With [frontend-dependencies](https://github.com/msurdi/frontend-dependencies) we can pull in just the dependency files we need, not an entire `node_modules` directory of cruft. Infact, nothing is put into the `node_modules` directory! By default, I just pull in 2 files for each dependency ( the develpment and the minified version) + +## Get Started + +Running `npm install` will install all the production build dependencies for when you need them and as a `postinstall` hook, will populate the `src/public/vender` directory will all the client-side dependencies. These are name-spaced. + +You can add or remove dependencies from the `package.json` file. Client-side dependencies are configured under `frontendDependencies`, which looks something like + +``` +"frontendDependencies": { + "target": "src/public/vendor/", + "packages": { + "riot": { + "version": "3.13.2", + "src": "*min.js", + "namespaced": true + }, + "riot-route": { + "version": "3.1.4", + "src": "dist/route.*", + "namespaced": true + }, + "grayscale": { + "src": "dist/*", + "url": "https://github.com/n2geoff/grayscale", + "namespaced": true + } + } +} +``` + +I found this to be, currently, the simplest way to manage client-side dependencies. + +[Learn More](https://github.com/msurdi/frontend-dependencies) on the github page for the lib diff --git a/docs/riotjs.md b/docs/riotjs.md deleted file mode 100644 index e69de29..0000000 diff --git a/gulpfile.js b/gulpfile.js index 2aa2a0c..359271a 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -70,5 +70,5 @@ gulp.task('assets', gulp.parallel('css', 'fonts', 'images', 'javascript', 'vendo // build everything for production distribution gulp.task('build', gulp.series('assets', 'public', 'index', 'tags'), () => {}); -// create task +// by default do this... gulp.task('default', gulp.series('build'), () => {});