riot-starter/README.md

128 lines
4.5 KiB
Markdown

# RiotJS App Starter
> 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 using [RiotJS](https://riot.js.org/) for the fastest way to iterate over UI for development -- **bar-none**.
No crazy syntax, just HTML, CSS and JavaScript.
No isolated eco-system, work with any library, any tool, any way you want!
[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.
What are you waiting for -- **GO FORTH AND BUILD YOUR APP, RAPIDLY!**
*Designed to be as simple as possible, but no simpler*
## Features
- [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
**Requirements**
- [NodeJS](https://nodejs.org/)
> 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**. 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.
`npm build` is still there. See Below.
### How
[RiotJS](https://riot.js.org/) [client-side 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.
## Getting Started
1. Run `npm install`, this will install all vendor dependencies
2. Start coding in `app`
3. run the `app/index.html` from your favorite web server\*
> \* try `live-server` from `npm` or via [Visual Studio Code]() plug-in it's awesome!
### Project Structure
```
app/ <-- 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
... <-- misc project meta files
```
### Web Components
Web-components are just `HTML` files wrapped in a custom `tag`, which means they can be as simple as
```html
<my-component>
<button>
Say Hello!
</button>
</my-component>
```
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 Guide](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 10kb
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.
## Testing
- TBD
## Additional Documentation
- [How Dependencies are Used](docs/dependencies.md)
## TODO
- compile vendor libs to vendor.js
- 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), they're minimalistic;)
## License
[MIT](LICENSE)