here comes xplat...
# Cross-platform (xplat) tools for Nx workspaces
When the need arises for cross-platform development in your Nx workspace you want versatility, clarity and best practices which are scalable.
**xplat** is an added value pack for [Nx](https://nrwl.io/nx) distributed via an Angular [schematic](https://blog.angular.io/schematics-an-introduction-dc1dfbc2a2b2) to provide out of the box support for cross-platform development.
With the strength of [TypeScript](https://www.typescriptlang.org/) paired with the power of [Angular](https://angular.io/) we can share a lot of code between various platforms to make our projects easier to maintain and develop.
# Install ## 1. Create a new Nx workspace
With a focus first approach to web development via TypeScript/JavaScript, the `xplat` value pack adds support for the following platforms:
* [Electron](https://electronjs.org/) * [Ionic](https://ionicframework.com) * [NativeScript](https://www.nativescript.org/) * [Nest](https://nestjs.com/)# Install ## 1. Create a new Nx workspace
npm install -g @nrwl/schematics
npm install -g @angular/cli
create-nx-workspace [your workspace name]
Please see [Nrwl Nx for full list of options here](https://nrwl.io/nx/guide-nx-workspace).
## 2. Install xplat tools
Navigate into your new workspace.
npm install @nstudio/schematics --save-dev
This will enhance your Nx workspace with all the `xplat` tools.
## 3. Generate xplat architecture
*Note*: prefix is required.
*Why?*: when sharing code it's important to scope things with a unique prefix.
ng g xplat --prefix=foo --platforms=web,nativescript,ionic,electron,nest
You can specify one or more combinations of platforms you'd like to work with. You can generate support for other platforms at anytime.
This will generate an opinionated structure available via the following barrels (substitue `workspace` with the name you used to set Nx up with):
* `libs/` platform agnostic code
* `@workspace/core`
* `@workspace/features`
* `@workspace/scss`
* `@workspace/utils`
* `xplat/` platform specific code
* `@workspace/electron`
* `@workspace/ionic`
* `@workspace/nativescript`
* `@workspace/web`
Learn more details about the structure [below](xplat/#codeexpanded).
This configuration will provide you with proven best practices while maximizing shared code across many different platform targets.
#### Benefits?
* Utilizing `libs` for purely platform agnostic code provides the ability to share a lot of code across all platforms/apps without fear of platform collisions in the future.
* Separating platform specific code into it’s own directories helps avoid mental overload and enables "developer modes" to allow easy hiding/showing of certain platforms for developer focus.
* Allow two or more different Ionic or NativeScript apps to share the same components/directives/style themes and more.
* Allow two or more Electron apps to share the same components/directives/style themes and more.
* Allows platform specific code to be built on top of and extend the base from `libs` providing ease of maintenance into the future.
* Manage all dependencies from the root of workspace while still allowing per app configuration as needed.
You can pass optional flags to configure desired platforms for your workspace:
ng g xplat --prefix=foo --platforms=web,ionic
ng g xplat --prefix=foo --platforms=nativescript
ng g xplat --prefix=foo --platforms=nativescript,web
ng g xplat --prefix=foo --platforms=electron
## 4. Add Web app
Use the standard Nx app generator:
ng g app name
The web app will be enhanced to take full advantage of the `xplat` setup generated above.
Full options can be [found here](https://nrwl.io/nx/guide-nx-workspace#create-an-app).
## 5. Add NativeScript app
*Prerequisites:* You will need to have [NativeScript](https://docs.nativescript.org/angular/start/quick-setup) installed.
ng g app.nativescript name
This will generate a NativeScript iOS/Android app inside the `apps` directory which takes full advantage of the `xplat` setup generated above.
## 6. Add Ionic app
*Prerequisites:* You will need to have `npm i -g ionic` installed.
This supports Ionic 4 with Capacitor.
ng g app.ionic name
This will generate an Ionic app inside the `apps` directory which takes full advantage of the `xplat` setup generated above.
You will need to prepare a few things for Capacitor development:
* Prepare iOS development with Capacitor:
npm run prepare.ionic.name.ios
* Prepare Android development with Capacitor:
npm run prepare.ionic.name.android
## 7. Add Electron app
ng g app.electron name --target=web-anyapp
This will generate an Electron app inside the `apps` directory which takes full advantage of the `xplat` setup generated above and will have the target web app wrapped up and ready to develop against.
## 8. Add Nest app
ng g app.nest name
This will generate an Nest app inside the `apps` directory.
## 9. Try things out
Ensure root workspace dependencies are successfully installed:
npm i
If you look at your `package.json` you will notice a pattern. Each has their own `start` script broken down as follows:
npm run start.[platform].[name].[extra?]
Given that pattern you can now run your web app with:
npm run start.web.name
Run NativeScript iOS app with:
npm run start.nativescript.name.ios
Run NativeScript Android app with:
npm run start.nativescript.name.android
Run Ionic app in browser for development:
npm run start.ionic.name
Open Ionic app in XCode:
npm run start.ionic.name.ios
Open Ionic app in Android Studio:
npm run start.ionic.name.android
Run Electron app with live reload:
npm run start.electron.name
You can build Electron for Windows, Linux and Mac with the following:
npm run build.electron.name.windows
npm run build.electron.name.linux
npm run build.electron.name.mac
Run Nest backend app:
npm run start.nest.name
Sometimes you may need to clean dependencies and reset:
* `npm run clean`: Cleans root dependencies (also resets package-lock.json)
* `npm run clean.nativescript.name`: Cleans NativeScript app
* `npm run clean.ionic.name`: Cleans Ionic app
This pattern runs throughout `xplat`. For example, if you added a `NativeScript` app named `viewer` you would then have the following scripts to manage your app:
npm run start.nativescript.viewer.ios
npm run start.nativescript.viewer.android
// iOS/Android are cleaned simultaneously
npm run clean.nativescript.viewer
## Developer modes
Oftentimes you have a team with various skillsets and specialties. Developer modes allow each developer to switch on/off particular platforms to enhance their focus:
* web only: `ng g mode web`
* electron only: `ng g mode electron`
* ionic only: `ng g mode ionic`
* nativescript only: `ng g mode nativescript`
* nest only: `ng g mode nest`
* fullstack (everything): `ng g mode fullstack`
Default is `fullstack`.
Supported IDE's:
* [VS Code](https://code.visualstudio.com/)
## Generate with a sample feature
xplat provides the ability to generate a sample feature from the start which serves as an example of how to share route config and base level component classes across all app targets. To generate the setup with the sample feature in tact:
ng g xplat --prefix=foo --sample --platforms=web,nativescript
ng g app yourapp --sample
**VERY IMPORTANT**: Choose `y` to the Routing question/prompt when generating the web app.
ng g app.nativescript yourapp --sample
You will find the xplat setup now has a sample feature `items` included which you can learn from.
## Further details The shared code structure expanded: * `libs/` platform agnostic code used everywhere. * `core/` * `base/` abstract classes * `environments/` config * `services/` low level services * `features/` single barrel import for various features * `ui/` components, directives and pipes * `scss/` base styles * `utils/` utilities * `xplat/` * `electron/` -> Electron shared code * `ionic/` -> Ionic shared code * `nativescript/` -> NativeScript shared code * `web/` -> Web shared code What is meant by *single barrel import for various features* with regards to `libs/features`? This means you can use any base feature functionality with `import { YourFeature } from '@[your workspace name]/features';` across the entire workspace. You can think of `libs/features/[any number of features]` as the base common denominator for any feature you plan to build out across any platform. You can start there with the basic setup for any feature development you plan on targeting with any number of platforms. You will generally keep the work there scoped to abstract base classes, models/interfaces, services and/or state for that feature. There is no `NgModule` in `libs/features/items` because the components are not decorated or declared there. They are instead decorated in their accompanying `xplat/[platform]/features/items` for specific platform view handling. However `NgModule`'s can be used for anything; they are certainly not constrained to just declaring components for example. You could have a `ItemsStateModule` in libs/features which might define and setup ngrx state which would be completely platform agnostic. We chose not to setup a state module with ngrx out of the box as we were unsure how many intend to use ngrx to start with. We might add this in the future if we find most folks want to use xplat with [ngrx](https://github.com/ngrx/platform) (or some other state library like [ngxs](https://github.com/ngxs/store) ). ## FAQ ### Why is there a package.json in some libs? For `scss` package imports across shared code and projects. ### Why is there a file:libs/scss dependency in root package.json? For convenient shared SASS usage throughout. If you look inside `xplat/web/scss/_variables.scss` you will see `@import '~@workspace/scss/common';` (substitute `workspace` with your name). This allows your web specific shared SASS to consume the entire workspace (**cross platform**) SASS from `libs` easily. ### Why is there a references.d.ts file in root of workspace? This allows full intellisense support across rich iOS/Android api's made available via NativeScript in your shared code in `xplat/nativescript`. ### When running web app I get a SASS error? You might experience this issue:
## Further details The shared code structure expanded: * `libs/` platform agnostic code used everywhere. * `core/` * `base/` abstract classes * `environments/` config * `services/` low level services * `features/` single barrel import for various features * `ui/` components, directives and pipes * `scss/` base styles * `utils/` utilities * `xplat/` * `electron/` -> Electron shared code * `ionic/` -> Ionic shared code * `nativescript/` -> NativeScript shared code * `web/` -> Web shared code What is meant by *single barrel import for various features* with regards to `libs/features`? This means you can use any base feature functionality with `import { YourFeature } from '@[your workspace name]/features';` across the entire workspace. You can think of `libs/features/[any number of features]` as the base common denominator for any feature you plan to build out across any platform. You can start there with the basic setup for any feature development you plan on targeting with any number of platforms. You will generally keep the work there scoped to abstract base classes, models/interfaces, services and/or state for that feature. There is no `NgModule` in `libs/features/items` because the components are not decorated or declared there. They are instead decorated in their accompanying `xplat/[platform]/features/items` for specific platform view handling. However `NgModule`'s can be used for anything; they are certainly not constrained to just declaring components for example. You could have a `ItemsStateModule` in libs/features which might define and setup ngrx state which would be completely platform agnostic. We chose not to setup a state module with ngrx out of the box as we were unsure how many intend to use ngrx to start with. We might add this in the future if we find most folks want to use xplat with [ngrx](https://github.com/ngrx/platform) (or some other state library like [ngxs](https://github.com/ngxs/store) ). ## FAQ ### Why is there a package.json in some libs? For `scss` package imports across shared code and projects. ### Why is there a file:libs/scss dependency in root package.json? For convenient shared SASS usage throughout. If you look inside `xplat/web/scss/_variables.scss` you will see `@import '~@workspace/scss/common';` (substitute `workspace` with your name). This allows your web specific shared SASS to consume the entire workspace (**cross platform**) SASS from `libs` easily. ### Why is there a references.d.ts file in root of workspace? This allows full intellisense support across rich iOS/Android api's made available via NativeScript in your shared code in `xplat/nativescript`. ### When running web app I get a SASS error? You might experience this issue:
ERROR in ./node_modules/css-loader?{"sourceMap":false,"import":false}!./node_modules/postcss-loader/lib?{"ident":"postcss","sourceMap":false}!./node_modules/sass-loader/lib/loader.js?{"sourceMap":false,"precision":8,"includePaths":[]}!./xplat/web/scss/_index.scss
Module build failed:
@import '~@[your workspace name]/scss/index';
^
File to import not found or unreadable: ~@[your workspace name]/scss/index.
You just need to install root dependencies: `npm install` in the root of your workspace.