You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 94498b0
Browse filesBrowse the repository at this point in the historyBrowse files
- What works: a Preview limits section listing what a compiled release refuses
at build time (Angular forms, [ngClass]/[ngStyle], route guards and
resolvers, <ng-content>, *pagerItem and the other refused Angular features,
binary-only plugins, and on Android an instance's own function for a class
method), and the known limit that converted values and arrays are copies.
- Angular's supported pipes and RxJS per platform.
- Configuration: stubPlugins, and a Plugin options section with an example of
pluginReplacements, pluginSources and stubPlugins.
- Getting started: core and the compiler must match; the webpack 5.111.1
workaround is gone now that @nativescript/webpack 5.0.39 is out.
Copy file name to clipboardExpand all lines: content/guide/publishing/compiled-configuration.md
+58Lines changed: 58 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -39,12 +39,69 @@ All of them go in `release`, or in a platform's `release`.
39
39
|`compiled`| Release builds are compiled instead of bundled for the JavaScript runtime. |
40
40
|`pluginReplacements`|`{ 'package': './path.ts' }`: replaces a package with a module of yours that has the same exports. For plugins that only make sense with a JavaScript runtime, such as over-the-air updates. |
41
41
|`pluginSources`|`{ 'package': '../checkout' }`: compiles a plugin from a local checkout of its source instead of fetching the published revision. |
42
+
|`stubPlugins`|`['nativescript-ui-listview']`: builds binary-only plugins as empty stand-ins. See [Plugin options](#plugin-options). |
42
43
|`allowUnimplementedProperties`| Builds even when the app sets a core property the compiled build doesn't apply, with a warning for each. |
43
44
|`allowCoreMismatch`| Builds with a `@nativescript/core` other than the one the compiler was made from, with a warning. |
44
45
|`allowUntestedFrameworks`| Builds with a framework version outside the [tested ones](/guide/publishing/compiled-differences#tested-framework-versions), with a warning. |
45
46
|`narrowKitKeeps`| Android: R8 keeps only what the kit's reflection needs. See [Android](/guide/publishing/compiled-android#minification-r8). |
46
47
|`generatedKit`| Android: `false` builds on the older hand-written kit instead of the one generated from core. |
47
48
49
+
## Plugin options
50
+
51
+
Paths are relative to the project. `ios.release` and `android.release` can set them per platform: `pluginReplacements`
52
+
and `pluginSources` merge by package over the top-level ones, while a platform's `stubPlugins` list replaces the
53
+
top-level list.
54
+
55
+
### `pluginReplacements`
56
+
57
+
Every import of the package resolves to a TypeScript module of your app instead. The module exports, typed, what
58
+
your app uses of the package. The package's native code isn't linked. Use it for a package that only makes sense
59
+
with a JavaScript runtime, a JavaScript-only package the compiler can't type, or a binary-only plugin you rewrite.
| A plugin that only makes sense with a JavaScript runtime (over-the-air updates) |`pluginReplacements: { '@norrix/client-sdk': './release/norrix.ts' }`|
56
113
| A plugin whose published source can't be found, or doesn't match its JavaScript |`pluginSources: { 'some-plugin': '../some-plugin' }`|
114
+
| A binary-only plugin (`nativescript-ui-*`) |`pluginReplacements`, or `stubPlugins: ['nativescript-ui-listview']`|
57
115
| You patch a plugin with patch-package | Write the same patch against the plugin's TypeScript source, in `native-release/patches/<package>+<version>.patch`. The compiler compiles the source, not the published JavaScript your patch changes. |
58
116
| You patch `@nativescript/core` with patch-package | The compiler recognizes common core patches and applies their effect. One it doesn't recognize stops the build. |
59
117
| An `Info.plist` with no `UIApplicationSceneManifest` (older templates) | Nothing: the build adds the template's and says so. |
|`ngPlural`, `ngPluralCase`, `ngComponentOutlet`; `ngIf`, `ngForOf` or `ngSwitchCase` on an element without `*`; `[ngTemplateOutlet]` anywhere but `<ng-container>`|`@if`, `@for`, `@switch`, or the `*` form |
122
+
|`<ng-content>` (content projection), and content inside an element that hosts an attribute-selected component | Pass the data as inputs and render it in the child's own template |
123
+
|`*pagerItem`, and structural directives other than `*ngIf`, `*ngFor`, `*ngTemplateOutlet`, `*ngSwitchCase` and `*ngSwitchDefault`| For a pager, `<Pager [items]>` with an `<ng-template let-item>`|
124
+
| Route guards and resolvers: `canActivate`, `canActivateChild`, `canDeactivate`, `canMatch`, `canLoad`, `resolve`| Check the condition where you navigate, and load the data in the routed component |
125
+
| Route fields other than `path`, `pathMatch`, `component`, `loadComponent`, `redirectTo`, `outlet`, `children`, `loadChildren`, `title` and `runGuardsAndResolvers` (such as `data`, `providers`, `matcher`) ||
126
+
| A `path`, `pathMatch`, `redirectTo` or `outlet` that isn't a string literal; a `component` that isn't a class name ||
127
+
| Router features other than `withPreloading()` and `withDebugTracing()`; `forRoot` options other than `enableTracing`, `useHash`, `preloadingStrategy`, `scrollPositionRestoration`, `anchorScrolling`, `scrollOffset`||
128
+
| In a routes table outside the app's entry (an NgModule's routing module): `children`, `loadChildren`, `loadComponent`, `outlet`, and a redirect from a path other than `''`| Give the routes to `provideNativeScriptRouter(routes)` in the entry |
129
+
| Angular's `routerLink` and `routerLinkActive`, and `nsRouterLinkActive`|`nsRouterLink`|
130
+
|`animate.enter`, `animate.leave` and animation events; `(window:…)` and `(document:…)` events ||
131
+
|`<ng-container>` with a `#ref`, an event, a directive of yours, or an input other than `ngSwitch`, `ngTemplateOutlet` and `ngTemplateOutletContext`||
132
+
|`<page-router-outlet>` with anything but `name` and `actionBarVisibility="auto"`||
|`viewChild()`, `viewChildren()`, `contentChild()`, `contentChildren()`; an `input()` or `model()` option other than `alias`; an `output()` option |`@ViewChild` and `@ViewChildren`|
135
+
| In a `@Directive`: fields other than `selector`, `inputs` and `host`; `input()`, `output()`, `model()` and signal queries; lifecycle hooks other than `ngOnInit`, `ngOnChanges`, `ngAfterViewInit`, `ngOnDestroy`||
136
+
| An app `@NgModule`'s `providers`||
137
+
| A plugin element whose `registerElement` meta adds its children itself (`insertChild`, `removeChild`), when it has children; one registered with `skipAddToDom`||
138
+
139
+
A name in the first rows that a directive or attribute-selected component of your own takes as an input is
140
+
yours, and isn't refused.
141
+
142
+
### Binary-only plugins
143
+
144
+
`nativescript-ui-listview`, `-sidedrawer`, `-calendar`, `-chart`, `-dataform`, `-autocomplete` and `-gauge` ship
145
+
no TypeScript source, so there is nothing to compile. The build stops and names each one, with two remedies:
146
+
replace the package with a module of your app (`release.pluginReplacements`), or build it as an empty stand-in
147
+
(`release.stubPlugins`). See [Configuration](/guide/publishing/compiled-configuration#plugin-options).
148
+
149
+
### Android: an instance's own function for a class method
150
+
151
+
Assigning a function to a method that a class compiled with your app declares (`logger.log = (m) => …`, where
152
+
`log` is a method of `Logger`) stops an Android build: "giving an instance its own Logger.log in place of the
153
+
class's method". In the Kotlin output, calls go straight to the class's method, so the assignment would be ignored.
154
+
iOS supports it. **Instead:** declare `log` as a field holding a function, or override the method in a subclass.
155
+
156
+
### Converted values are copies, not the same object (iOS and Android)
157
+
158
+
This one compiles and runs, and behaves differently. A value with no static type (`any`, parsed JSON, a value from
159
+
a non-strict module) becomes a typed object where your code gives it an interface type. That conversion makes a new
160
+
object each time:
161
+
162
+
- The same object read as an interface twice gives two objects: `a === b` is `false`, so are their arrays
163
+
(`a.items === b.items`), and a `Map` or `Set` keyed by one doesn't find the other. A memoized selector that
164
+
compares its input by identity recomputes every time.
165
+
- A typed array (`Float32Array`), or an untyped array, passed to a `number[]` parameter is copied, so what the
166
+
function writes into it doesn't reach the caller's array. On Android, an untyped array whose elements already
167
+
have the parameter's element type is passed as it is.
168
+
169
+
**Instead:** give the value its type once, where it enters your code, and pass that typed reference on. Compare
170
+
records by an id rather than `===`. Have a function return the values it computes instead of writing into an
171
+
array argument, or pass it a `number[]`.
172
+
104
173
## JavaScript coverage
105
174
106
175
The compiler is also run against [test262](https://github.com/tc39/test262), the JavaScript conformance suite.
Until `@nativescript/webpack` 5.0.39 is out, a new webpack-based project needs `npm install -D webpack@5.111.1` for `ns run` (the JavaScript dev loop). Compiled builds aren't affected.
27
-
:::
28
-
29
25
The CLI runs the compiler from your project's `node_modules`. The build stops if your `@nativescript/core` is not
30
26
the version the compiler was made from, or if your framework is outside the
0 commit comments