riot-starter/README.md

136 lines
5.1 KiB
Markdown
Raw Normal View History

2018-11-30 10:17:45 +00:00
# RiotJS App Starter
2018-12-02 07:21:35 +00:00
> A Rapid Application Starter kit for RiotJS minimalists
2018-03-22 20:37:34 +00:00
2018-12-02 07:26:38 +00:00
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**.
2018-03-22 20:37:34 +00:00
2018-12-02 07:26:38 +00:00
No crazy syntax, just HTML, CSS and JavaScript.
2018-11-30 10:17:45 +00:00
2018-12-02 07:26:38 +00:00
No isolated eco-system, work with any library, any tool, any way you want!
2018-03-22 20:37:34 +00:00
2018-12-02 07:21:35 +00:00
[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.
2018-11-30 10:17:45 +00:00
2018-12-02 07:21:35 +00:00
What are you waiting for -- **GO FORTH AND BUILD YOUR APP, RAPIDLY!**
2018-11-30 10:17:45 +00:00
2018-12-02 07:21:35 +00:00
*Designed to be as simple as possible, but no simpler*
2018-03-22 20:37:34 +00:00
2018-12-02 07:21:35 +00:00
## Features
2018-03-22 20:37:34 +00:00
2018-12-02 07:21:35 +00:00
- [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
2019-07-20 23:05:55 +00:00
- [Require1k](http://stuk.github.io/require1k/) tiny CommonJS module system for mixins/libs
2018-12-02 07:21:35 +00:00
- [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
2018-11-30 10:17:45 +00:00
2018-12-02 07:21:35 +00:00
**Requirements**
2018-11-30 10:17:45 +00:00
2018-12-02 07:26:38 +00:00
- [NodeJS](https://nodejs.org/)
2018-11-30 10:17:45 +00:00
2018-12-02 07:21:35 +00:00
> Installs `vendor/` dependencies and `npm build` to get your project into production
2018-11-30 10:17:45 +00:00
2018-03-22 20:37:34 +00:00
## Why Zero-Build?
**SPEED!**
2018-12-02 07:21:35 +00:00
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.
2018-03-22 20:37:34 +00:00
2018-12-02 07:21:35 +00:00
`npm build` is still there. See Below.
2018-03-22 20:37:34 +00:00
2018-12-02 07:21:35 +00:00
### How
2018-03-22 20:37:34 +00:00
2019-02-19 16:26:32 +00:00
[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.
2018-11-30 10:17:45 +00:00
2018-12-02 07:21:35 +00:00
## Getting Started
2018-11-30 10:17:45 +00:00
2018-12-02 07:21:35 +00:00
1. Run `npm install`, this will install all vendor dependencies
2018-11-30 10:17:45 +00:00
2. Start coding in `public`
2018-12-02 07:21:35 +00:00
2019-07-20 23:05:55 +00:00
3. run the `public/index.html` from your favorite web server
2018-11-30 10:17:45 +00:00
2019-07-20 23:05:55 +00:00
> try `live-server` from `npm` or via [Visual Studio Code]() plug-in it's awesome!
2018-12-02 07:21:35 +00:00
### Project Structure
2018-03-22 20:37:34 +00:00
2018-11-30 10:17:45 +00:00
```
2019-07-20 23:05:55 +00:00
public/ <-- develop here
css/ <-- your css files
js/ <-- your javascript files
config/ <-- configuration files used in app.js
config.js <-- global app settings, such as version
routes.js <-- routes combined
mixins.js <-- mixins combined
mixins/ <-- collection of mixins
relay.mixin.js <-- global observeable mixin
store.mixin.js <-- localStorage mixin
app.js <-- application 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
2018-11-30 10:17:45 +00:00
README.md
2019-07-20 23:05:55 +00:00
... <-- misc project meta files
2018-12-02 07:21:35 +00:00
```
### 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>
2018-11-30 10:17:45 +00:00
```
2018-12-02 07:21:35 +00:00
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
2018-03-22 20:37:34 +00:00
2018-12-02 07:21:35 +00:00
Of course we want our component to do more, so...
2018-12-02 07:26:38 +00:00
...*for now*, go check out the [RiotJS Guide](https://riot.js.org/guide/)
2018-12-02 07:21:35 +00:00
## Build for Production
2019-02-19 16:26:32 +00:00
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
2018-12-02 07:21:35 +00:00
2019-01-01 16:52:46 +00:00
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.
2018-03-22 20:37:34 +00:00
2018-11-30 10:17:45 +00:00
## Testing
- TBD
2018-03-22 20:37:34 +00:00
2018-12-02 07:21:35 +00:00
## Additional Documentation
2019-01-01 16:52:46 +00:00
- [How Dependencies are Used](docs/dependencies.md)
2019-07-20 23:05:55 +00:00
- [Module System](docs/modules.md)
2018-12-02 07:21:35 +00:00
2018-11-30 10:17:45 +00:00
## TODO
2018-03-22 20:37:34 +00:00
2019-01-01 16:56:46 +00:00
- compile vendor libs to vendor.js
2018-12-02 07:21:35 +00:00
- Include a testing framework [Jasmine](https://jasmine.github.io/), [test.it](https://github.com/n2geoff/testit), or?
2018-12-02 07:26:38 +00:00
- Is good AJAX support the missing ingredient? or is`fetch` good enough?
2018-11-30 10:17:45 +00:00
- add routing example
2018-12-02 07:21:35 +00:00
## Support
Please open [an issue](http://code.negative9.net/geoff/riot-starter/issues/new) for support.
## Contributing
2019-01-01 16:52:46 +00:00
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;)
2018-12-02 07:21:35 +00:00
## License
[MIT](LICENSE)