|
1 | 1 | # @liferay/cli |
2 | 2 |
|
3 | | -This project hosts the Liferay JS Toolkit CLI Tool |
| 3 | +This project hosts the Liferay JS Toolkit CLI Tool. |
| 4 | + |
| 5 | +Inspired by other frameworks, like React, Angular, or Vue.js, the Liferay JS |
| 6 | +Toolkit provides a CLI tool to invoke all implemented features, like project |
| 7 | +generation, build, deployment, etc. |
| 8 | + |
| 9 | +> 👀 Note that this tool still uses the JS Toolkit under the hood, so please |
| 10 | +> refer to |
| 11 | +> [its documentation](https://github.com/liferay/liferay-frontend-projects/blob/master/maintenance/projects/js-toolkit/docs/README.md) |
| 12 | +> for more details on configuration and behavior. |
| 13 | +
|
| 14 | +## Installation |
| 15 | + |
| 16 | +The `@liferay/cli` tool may be installed globally using `npm install -g @liferay/cli` or `yarn global add @liferay/cli`, to make it available from the |
| 17 | +command line. |
| 18 | + |
| 19 | +However, if you don't want to mess with global installations, you can also run |
| 20 | +it using `npx @liferay/cli ...`. This ensures that you always use the latest |
| 21 | +version, and won't install it locally. |
| 22 | + |
| 23 | +If you install globally, simple invoke `liferay` from the command line, which |
| 24 | +is the name of the |
| 25 | +[binary provided by `@liferay/cli`](https://github.com/liferay/liferay-frontend-projects/blob/master/projects/js-toolkit/packages/liferay-cli/bin/liferay.js). |
| 26 | + |
| 27 | +## Available actions |
| 28 | + |
| 29 | +Currently, the `@liferay/cli` tool supports the following features: |
| 30 | + |
| 31 | +- [Project generation](#project-generation) |
| 32 | +- [Project adaptation](#project-adaptation) |
| 33 | +- [Project build](#project-build) |
| 34 | +- [Project deployment](#project-deployment) |
| 35 | +- [Project clean](#project-clean) |
| 36 | + |
| 37 | +## Project generation |
| 38 | + |
| 39 | +Project generation lets you create new projects for the following |
| 40 | +frameworks[^1]: |
| 41 | + |
| 42 | +- [React](https://reactjs.org/) |
| 43 | +- [Angular](https://angular.io/) |
| 44 | +- [Vue.js](https://vuejs.org/) |
| 45 | + |
| 46 | +> 👀 This feature is a replacement of the |
| 47 | +> [older Yeoman Liferay JavaScript generator](https://github.com/liferay/liferay-frontend-projects/tree/master/maintenance/projects/js-toolkit/packages/generator-liferay-js) |
| 48 | +> but it doesn't rely on Yeoman any more. |
| 49 | +
|
| 50 | +### Usage |
| 51 | + |
| 52 | +```sh |
| 53 | +$ liferay new my-project ↩ |
| 54 | +``` |
| 55 | + |
| 56 | +The above command will start a wizard that will generate a project called |
| 57 | +`my-project` in the current folder. Simply answer the questions you are asked, |
| 58 | +and let the generator do its duties. |
| 59 | + |
| 60 | +Once the project is created, you may change to its folder and run |
| 61 | +`npm|yarn install` to install the dependencies, then invoke the supported |
| 62 | +actions (like `build`, `deploy`, etc.) with `npm|yarn run <command>`. |
| 63 | + |
| 64 | +#### Target platform |
| 65 | + |
| 66 | +One of the key questions in the wizard is related to the platform you wish to |
| 67 | +target. A target platform defines: |
| 68 | + |
| 69 | +- The set of rules to build the project |
| 70 | +- The default dependencies of the project |
| 71 | + |
| 72 | +So, for example, when using |
| 73 | +[`portal-7.4-ga1`](https://github.com/liferay/liferay-frontend-projects/tree/master/target-platforms/packages/portal-7.4-ga1) |
| 74 | +you are saying that your project will be deployed to Liferay Portal CE 7.4 GA1 |
| 75 | +and thus your project will have access to |
| 76 | +[any JavaScript API available in that version](https://github.com/liferay/liferay-frontend-projects/blob/master/target-platforms/packages/portal-7.4-ga1/config.json#L21-L171) |
| 77 | +(for instance, if you use React, the copy of `react` that comes bundled with |
| 78 | +Liferay Portal will be used in your project, instead of referring to a new one, |
| 79 | +local to the project). |
| 80 | + |
| 81 | +Note that, if you don't want to couple your project to any version of |
| 82 | +Liferay Portal, you may choose to use the |
| 83 | +[`portal-agnostic`](https://github.com/liferay/liferay-frontend-projects/tree/master/target-platforms/packages/portal-agnostic) |
| 84 | +target platform. By choosing the agnostic platform your project will not be |
| 85 | +injected with any of the packages that come bundled with Liferay Portal. |
| 86 | + |
| 87 | +## Project adaptation |
| 88 | + |
| 89 | +Project adaptation lets you transform you native React, Angular and Vue.js |
| 90 | +projects[^1] into Liferay widgets that you can deploy to your Liferay Portal |
| 91 | +instance[^2]. |
| 92 | + |
| 93 | +> 👀 This feature is a replacement of the |
| 94 | +> [older Yeoman Liferay JavaScript generator](https://github.com/liferay/liferay-frontend-projects/tree/master/maintenance/projects/js-toolkit/packages/generator-liferay-js) |
| 95 | +> but it doesn't rely on Yeoman any more. |
| 96 | +
|
| 97 | +### Usage |
| 98 | + |
| 99 | +In your native project's directory run: |
| 100 | + |
| 101 | +```sh |
| 102 | +$ liferay adapt ↩ |
| 103 | +``` |
| 104 | + |
| 105 | +The above command will start a wizard that will adapt your project to be |
| 106 | +deployable to Liferay portal. |
| 107 | + |
| 108 | +Once the project is adapted you may use the `build:liferay`, `deploy:liferay`, |
| 109 | +`clean:liferay`, etc. tasks to perform the same tasks you would do for a true |
| 110 | +Liferay project (ie: one that had been generated with `liferay new`). |
| 111 | + |
| 112 | +Learn more about project adaptation in |
| 113 | +[JS Toolkit's documentation on adaptation](https://github.com/liferay/liferay-frontend-projects/blob/master/maintenance/projects/js-toolkit/docs/How-to-adapt-most-popular-frameworks-projects.md#supported-projects). |
| 114 | + |
| 115 | +## Project build |
| 116 | + |
| 117 | +The `build` command will build your project and leave the resulting JAR file in |
| 118 | +the `dist` directory. You may then deploy it to a Liferay Portal instance |
| 119 | +copying the file by hand, or using the [Liferay deployment](#project-deployment) |
| 120 | +feature. |
| 121 | + |
| 122 | +### Usage |
| 123 | + |
| 124 | +```sh |
| 125 | +$ liferay build ↩ |
| 126 | + |
| 127 | +# or |
| 128 | + |
| 129 | +$ npm run build ↩ |
| 130 | + |
| 131 | +# or |
| 132 | + |
| 133 | +$ yarn build ↩ |
| 134 | +``` |
| 135 | + |
| 136 | +Note that `npm|yarn run build` is an alias to `liferay build` (you can see that |
| 137 | +by inspecting your project's `package.json` file). |
| 138 | + |
| 139 | +## Project deployment |
| 140 | + |
| 141 | +The `deploy` command will copy the JAR file created by the |
| 142 | +[project build](#project-build), in the `dist` directory, to your local Liferay |
| 143 | +Portal instance. |
| 144 | + |
| 145 | +The first time you run this task it will ask you for your Liferay Portal |
| 146 | +directory and store your answer in a `.liferay.json` file in your project for |
| 147 | +subsequent runs. |
| 148 | + |
| 149 | +### Usage |
| 150 | + |
| 151 | +```sh |
| 152 | +$ liferay deploy ↩ |
| 153 | + |
| 154 | +# or |
| 155 | + |
| 156 | +$ npm run deploy ↩ |
| 157 | + |
| 158 | +# or |
| 159 | + |
| 160 | +$ yarn deploy ↩ |
| 161 | +``` |
| 162 | + |
| 163 | +Note that `npm|yarn run deploy` is an alias to `liferay deploy` (you can see |
| 164 | +that by inspecting your project's `package.json` file). |
| 165 | + |
| 166 | +## Project clean |
| 167 | + |
| 168 | +The `clean` command will delete the `build` and `dist` directories created by |
| 169 | +[project build](#project-build) and [project deployment](#project-deployment) |
| 170 | +tasks. |
| 171 | + |
| 172 | +### Usage |
| 173 | + |
| 174 | +```sh |
| 175 | +$ liferay clean ↩ |
| 176 | + |
| 177 | +# or |
| 178 | + |
| 179 | +$ npm run clean ↩ |
| 180 | + |
| 181 | +# or |
| 182 | + |
| 183 | +$ yarn clean ↩ |
| 184 | +``` |
| 185 | + |
| 186 | +Note that `npm|yarn run clean` is an alias to `liferay clean` (you can see |
| 187 | +that by inspecting your project's `package.json` file). |
| 188 | + |
| 189 | +## Internal architecture |
| 190 | + |
| 191 | +The big majority of `@liferay/cli`'s source code is devoted to project |
| 192 | +generation and adaptation, this what previously located in our Yeoman |
| 193 | +generator. |
| 194 | + |
| 195 | +The rest of the commands (those used on generated/adapted projects) are simply |
| 196 | +delegated to the selected target platform (see |
| 197 | +[Target platform](#target-platform) above). |
| 198 | + |
| 199 | +That means that, in those cases the `liferay` command is simply a bridge that |
| 200 | +looks inside your project's `node_modules` folder to locate the selected target |
| 201 | +platform and invoke it to do its duties. |
| 202 | + |
| 203 | +This eases maintenance and evolution of `@liferay/cli` because we don't need to |
| 204 | +maintain a huge monolith of code targeting disparate targets. |
| 205 | + |
| 206 | +To gain more insights on target platforms and what they are intended for, you |
| 207 | +may have a look at |
| 208 | +[their project directory](https://github.com/liferay/liferay-frontend-projects/tree/master/target-platforms). |
| 209 | + |
| 210 | +--- |
| 211 | + |
| 212 | +[^1]: |
| 213 | + We aim to support the latest version of these frameworks but, given the |
| 214 | + fast pace at which they evolve, there may be some lag between the time when a |
| 215 | + framework's version is published and the time `@liferay/cli` supports it. |
| 216 | + |
| 217 | +[^2]: |
| 218 | + Note that adaptation is a best effort heuristic process so don't expect |
| 219 | + every native framework functionality to work when a project is adapted. This |
| 220 | + is mainly due to the fact that there's some mismatch between these |
| 221 | + frameworks' application model (they assume a SPA deployed as a single webapp) |
| 222 | + and the one of Liferay, that assumes that many unrelated portlets cooperate |
| 223 | + together to produce a single HTML page. |
0 commit comments