explain flavors in detail #90
Conversation
| @@ -7,6 +7,8 @@ Create [Cycle.js](https://cycle.js.org/) apps with no build configuration. | |||
| * [Getting Started](#getting-started) – How to create a new app. | |||
| * [Custom Flavors](#flavors) – How to develop and publish new flavors | |||
|
|
|||
| The project is inspired by [create-react-app](https://github.com/facebookincubator/create-react-app) | |||
There was a problem hiding this comment.
I think we have a special mention for this on the Acknowledgements section, I'll rather keep it one place only.
|
|
||
| ## Why Use This? | ||
|
|
||
| **If you’re getting started** with Cycle.js, use `create-cycle-app` to automate the build of your app. There is no configuration file, and `cycle-scripts-<flavorName>` is the only extra build dependency in your `package.json`. Your environment will have everything you need to build a Cycle.js app. | ||
|
|
||
| **If you’re a power user** simply use it as a boilerplate generator, by passing in your own flavor. | ||
|
|
||
| **To customise** the build or compile process, you need to first `eject` the dependencies and configurations into the project root folder. Then you can customize from there as usual. |
There was a problem hiding this comment.
Not sure this fit into the "Why use this" section
|
|
||
| ## Getting Started | ||
|
|
||
| ### Installation | ||
|
|
||
| Installing globally provides a create-cycle-app command for creating new projects. | ||
| Install the module globally and a `create-cycle-app` binary command will be made available for creating new projects. |
There was a problem hiding this comment.
I guess we could remove some jargon and make it clearer that you will be able to use that command on your terminal perhaps?
| **We recommend** to use Node >= 6 and npm >= 3 for faster installation speed and better disk usage. You can use a node version manager(i.e [nodenv](https://github.com/nodenv/nodenv), [nvm](https://github.com/creationix/nvm), [n](https://github.com/tj/n)) to easily switch Node versions among different projects. | ||
| **We recommend** using Node >= 6 and npm >= 3 for faster installation speed and better disk usage. You can use a node version manager(i.e [nodenv](https://github.com/nodenv/nodenv), [nvm](https://github.com/creationix/nvm), [n](https://github.com/tj/n)) to easily switch Node versions among different projects. | ||
|
|
||
| `sudo n latest` - Install latest Node version |
There was a problem hiding this comment.
we suggest to use either nvm or n, but here we offer a specific command to run that imply the user is using n. I guess that suggesting few alternatives for managing node versions is more then enough, going into offering how to install node feels a bit out of scope imho, no?
|
|
||
| ### Creating an App | ||
|
|
||
| To create a new cycle.js app, run: | ||
|
|
||
| ``` | ||
| ```sh |
|
|
||
| Custom flavors allow generating starting projects to fulfil specific needs. | ||
| They can be published to npm, or being used locally via the create-cycle-app CLI. | ||
| They can be published to npm or a git repo or even be referenced locally (esp. useful when you create your _own_ custom flavor - see below) |
|
|
||
| The flavor will be installed via `npm install` and can therefore reference any flavor resource installable via `npm` |
There was a problem hiding this comment.
not sure I get this, what do you wanted to say with "and can therefore reference any flavor resource installable via npm" ?
There was a problem hiding this comment.
Thank you @kristianmandrup
I left you some comments, I think you definitely added some very good points, let's keep revise this and we'll have an awesome documentation!
|
|
||
| If you want to use a [lerna](https://github.com/lerna/lerna) repo with multiple packages, you can make a [sparse checkout](https://gist.github.com/sumardi/5559896) of the specific package you want to use as the base. | ||
|
|
||
| We recommend you use [one-fits-all](https://github.com/cyclejs-community/create-cycle-app-flavors/tree/master/packages/cycle-scripts-one-fits-all) as a baseline (note: it uses [webpack-blocks](https://github.com/andywer/webpack-blocks)) |
There was a problem hiding this comment.
I would try to keep as a basic suggestion the core flavor that come with cca, we could definitely point out to one-fits-all as an example for a more articulated flavor perhapsh? This simply because by doing so will make the readme a bit more future-proof, let's say one-fit-all will become core, or the core flavor will evolve...
There was a problem hiding this comment.
Maybe a bit long on flavors, creating your own etc. Perhaps add a Wiki instead with more detailed recipes ;)
| ``` | ||
|
|
||
| ##### Flavors: | ||
|
|
||
| - Check [available flavors](https://github.com/cyclejs-community/create-cycle-app-flavors) | ||
|
|
||
| ### Creating a custom flavor |
There was a problem hiding this comment.
This part is definitely interesting but I found it a bit unclear atm. Why not focusing on explaining better how to create a flavor and less on lerna technicalities? (We use lerna for managing this mono-repo and the flavors mono-repo, but i'm not too sure is of any relevance for a flavor creator) ..apart the sparse checkout mention, good one!
Hi guys,
You are welcome to use this Readme update as you like. At least it helped me better understand how to use flavors. Might be useful for other newbies. A good, clear starting point is essential for any "framework" community ;) Too much information to memorize and assumptions to make otherwise. Sorry to cause so much "trouble"...
Please let me know if I still have some misunderstandings or made some mistakes.
My big takeaway is that in order to customise anything, you have to
ejectand work from there so it really is just a sandbox environment/playground. I understand that the basic concept is taken from React. Wondering why you still are not using inquirer/templates though? Maybe next version!Cheers!