Projects are the consumers of extensions and will typically be applications, components and modules. They will often be instantiated from templates that will use a specific set of extensions for some predefined purpose.
This document will serve as a basic introduction about how Roc works and highlight the important parts for project developers.
For something to be consider a valid Roc project it needs to have at least one dependency on a Roc package. This dependency can be specified in several ways but in the most cases the user will not need to do anything.
See here for all of the different ways to specify what extensions a project should use.
When you are creating a new project you can either create it manually or use the Roc CLI.
We will assume that you have installed roc globally which gives us access to it on the command line.
You have two options when creating a new project with roc, either using roc create new or roc create init. new will create a new folder in which the project will be instantiated while init will use the current folder. We will use init but pick the one that fits your use case.
See more about the two commands here.
Tip: Roc will automatically find commands in groups like "create", we can use roc init without "create" here.
We will now create a new React project.
$ mkdir my-react-project
$ cd my-react-project
$ roc init web-app-reactThat is it, we now have a project with some example code using React and Roc.
The only thing you really need to create a new Roc project is to setup a npm project and add at least one Roc package that you want to use. We will create a React project here as an example.
$ mkdir my-project
$ cd my-project
$ npm init
$ npm install roc-package-web-app-react --save
$ npm install roc-package-web-app-react-dev --save-devWe now have a working project that we can start adding code to.
Let's assume we have a existing Roc project, how can we interact with it?
If roc has been installed globally it's possible to just run commands straight inside the project root. The available commands will change depending on the extensions that are used in the project and to see the current ones you can simply type roc.
If roc is not installed globally it could be a good idea to add an alias to it in the package.json. This can be done using a npm script like below.
script: {
"roc": "roc"
}Then it's possible to run npm run roc to get the available commands. You could also add the alias under start to save a little typing.
script: {
"start": "roc"
}Now it is possible to run with just npm start.
Read here for how the CLI works in more detail.
A useful thing that is possible to do in Roc projects is to generate documentation for the current setup in a project. This can be done by calling roc meta docs, or just roc docs. When doing this a ROC.md will be added to the project along with a docs/ folder containing markdown documentation. This documentation contains everything from the available commands to all possible settings and much more.
Roc will by default look for a roc.config.js file in the root of the project that can be used to override default configuration from extensions. The easiest way to know what is possible to configure is to either look at the generated documentation or use roc meta list-settings command.
Read here for more information about how configuration works in projects.
Roc will add a runtime by default when using the CLI. This runtime will make sure that the project is valid and also provide access to the configuration if needed and provide potential dependencies that extensions has exported to the project. Project developers will generally not need to know how the runtime functions in detail and it will just work in almost all situations.