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
You may create a custom template for your projects. The best place to start is to use one of the Official templates as a base and applying your changes on top.
106
106
107
+
The easiest and straight-forward way to create your customized template is to clone one of the blank templates. NativeScript templates come in different flavors (Plain JavaScript, TypeScript, Angular and Vue.js) so you could select the blank template for the desired application flavor.
108
+
109
+
Here is the list of the six main blank templates depending on the coding language preferences.
110
+
111
+
- Plain JavaScript template at [https://github.com/NativeScript/nativescript-app-templates/tree/master/packages/template-blank](https://github.com/NativeScript/nativescript-app-templates/tree/master/packages/template-blank)
112
+
- TypeScript template at [https://github.com/NativeScript/nativescript-app-templates/tree/master/packages/template-blank-ts](https://github.com/NativeScript/nativescript-app-templates/tree/master/packages/template-blank-ts)
113
+
- Angular template at [https://github.com/NativeScript/nativescript-app-templates/tree/master/packages/template-blank-ng](https://github.com/NativeScript/nativescript-app-templates/tree/master/packages/template-blank-ng)
114
+
- Vue.js template at [https://github.com/NativeScript/nativescript-app-templates/tree/master/packages/template-blank-vue](https://github.com/NativeScript/nativescript-app-templates/tree/master/packages/template-blank-vue)
115
+
- React template at [https://github.com/NativeScript/nativescript-app-templates/tree/master/packages/template-blank-react](https://github.com/NativeScript/nativescript-app-templates/tree/master/packages/template-blank-react)
116
+
- Svelte template at [https://github.com/NativeScript/nativescript-app-templates/tree/master/packages/template-blank-svelte](https://github.com/NativeScript/nativescript-app-templates/tree/master/packages/template-blank-svelte)
117
+
118
+
Creating your template is as simple as cloning the wanted template repository and modifying the source code to satisfy your business logic.
As of NativeScript 4.x.x the application templates have a mobile application structure so you could develop your template by following the standard developer workflow.
125
+
126
+
```JS
127
+
cd template-blank-ts
128
+
npm i
129
+
ns run android
130
+
// start making code changes
131
+
```
132
+
107
133
## Versioning Scheme
108
134
109
135
`@nativescript/core` does not follow Semantic Versioning. Major framework releases are released every six months (~March and ~September), while minor and patch releases may be released as often as every week. Patch releases should never contain breaking changes, however minor, and major releases can. We strive to note any breaking changes in the Changelogs, to make upgrades as easy as possible.
110
136
111
137
When referencing the `@nativescript/core` package, you should use a fixed version constraint such as `7.0.11`, or alternatively `~7.0.11` to allow installing patch updates.
138
+
139
+
## Guidelines
140
+
141
+
### Template Structure Guidelines
142
+
143
+
- Create folders named for the feature area they represent. Each featured area should be placed in a separate folder in the template's folder structure.
144
+
145
+
- Place each page, view model, and service in its file. Apply the single responsibility principle (SRP) to all pages, view models, services, and other symbols. This helps make the app cleaner, easier to read and maintain, and more testable.
146
+
147
+
- Consider creating a folder for a page when it has multiple accompanying files (.ts, .xml, .scss/css, etc.).
148
+
149
+
- Avoid putting all of your app template's code in a root folder named _app_. When the actual app is created from the template, all of the template's code will indeed go inside a root **app** folder, but you MUST NOT define this folder in the hierarchy of your template; otherwise, the `ns create` CLI command will not function properly.
150
+
151
+
### Package.json Guidelines
152
+
153
+
- Place a `package.json` file in the root folder of your app template.
154
+
Note this is not the actual root package.json of the generated mobile app – it is only used by the `ns create` CLI command upon app creation. Do not expect that everything you place in your package.json will be transferred to the actual package.json file. Notably `scripts` property content is removed. However, if you provide preinstall / postinstall scripts, they will be executed before getting removed. You can use this mechanism to generate/move settings files to the root folder of the generated app and generate actual "scripts" content for the resulting app package.json – see [copying settings files](https://github.com/NativeScript/template-master-detail-ts/blob/master/tools/preinstall.js) and [generating `scripts` commands on-the-fly](https://github.com/NativeScript/template-master-detail-ts/blob/master/tools/postinstall.js) for concrete examples.
155
+
156
+
- Provide a value for the `name` property using the format: **ns-template-[custom-template-name-goes-here]-ts**.
157
+
Note this property value is NOT transferred to the root package.json file generated by the `ns create` CLI command but can be found in the app/package.json file of the generated app.
158
+
159
+
- Provide a value for the `version` property following semver rules (e.g., 1.0.0).
160
+
Note this property value is NOT transferred to the root package.json file generated by the `ns create` CLI command but can be found in the app/package.json file of the generated app.
161
+
162
+
- Provide a value for the `main` property specifying the primary entry point to your app (usually **app.js**).
163
+
Note this property value is NOT transferred to the root package.json file generated by the `ns create` CLI command but can be found in the app/package.json file of the generated app.
164
+
165
+
- Provide a value for the `android` property specifying V8 flags (at a minimum it should be set to `"android": { "v8Flags": "--expose_gc" }`).
166
+
Note this property value is NOT transferred to the root package.json file generated by the `ns create` CLI command but can be found in the app/package.json file of the generated app.
167
+
168
+
- Provide a value for the `displayName` property (user-friendly template name).
169
+
Note this property value is NOT transferred to the root package.json file generated by the `ns create` CLI command.
170
+
171
+
- Provide a value for the `repository` property specifying the place where your code lives.
172
+
173
+
- Note this property value is NOT transferred to the root package.json file generated by the `ns create` CLI command.
174
+
175
+
- Note correct `repository` property value is essential for the future integration with NativeScript Marketplace. Check the following section “Marketplace guidelines” for other integration requirements as well.
176
+
177
+
- Provide a value for the following additional set of package.json properties: `description`, `license`, `readme`, `dependencies`, `devDependencies`.
178
+
Note these property values are transferred to the root package.json file generated by the `ns create` CLI command.
179
+
For example, [package.json](https://github.com/NativeScript/nativescript-app-templates/blob/master/packages/template-master-detail-ts/package.json) has the following minimal structure:
- Provide a value for the `keywords`. Keywords can be very helpful for the discoverability of the template. Also, there are special keywords that could be used to make the template appear in the [NativeScript marketplace](https://market.nativescript.org/) especially and under certain conditions. The following keywords are supported:
207
+
-`ux-preview` - will add an “Preview & Vote” label on the "preview box" in the search list. It will also enable email registration and voting. This keyword should be used when adding a "preview" of a template that is not implemented but is rather an idea.
208
+
-`category-general` - will show the template under the "General" tab in the ["Templates" page](https://market.nativescript.org/?tab=templates). This is the general or basic category, used to describe "generic" functionality.
209
+
-`category-healthcare` - will show the template under the "Healthcare" tab in the ["Templates" page](https://market.nativescript.org/?tab=templates). This is a special category, used to describe a template with functionality related to the healthcare industry.
210
+
211
+
### Marketplace Guidelines
212
+
213
+
- Publish your app template to npm (https://www.npmjs.com/) using **ns-template-[custom-template-name-goes-here]-ts** format for the npm package name.
214
+
215
+
- Provide a screenshot preview to be used in a future NativeScript Marketplace integration under **tools/assets/marketplace.png** in your app template folder structure.
216
+
Check [tools/postinstall.js](https://github.com/NativeScript/template-master-detail-ts/blob/master/tools/postinstall.js) that implements a mechanism for removing the "tools" infrastructure folder from the generated app.
217
+
218
+
- Provide correct `repository` property value in the root package.json file of your app template (see the "Package.json guidelines" section above for additional package.json requirements).
219
+
220
+
-[Read more](https://github.com/NativeScript/marketplace-feedback/blob/master/docs/template-submission.md) how to submit your app template to [NativeScript Marketplace](https://market.nativescript.org).
221
+
222
+
### Styling Guidelines
223
+
224
+
- Consider using the [NativeScript core theme](https://github.com/NativeScript/theme) for styling your app template.
225
+
226
+
- Consider using the following infrastructure to enable cross-platform SASS styling for your app template:
227
+
**\_app-variables.css** file in the app template's root folder should import the NativeScript core theme variables, and any custom colors or theme variable overrides you might use:
228
+
229
+
```CSS
230
+
/*
231
+
Import the theme's variables. If you're using a color scheme
232
+
other than "light", switch the path to the alternative scheme,
233
+
for example '~nativescript-theme-core/scss/dark'.
234
+
*/
235
+
@import'~nativescript-theme-core/scss/light';
236
+
237
+
/* Custom colors */
238
+
$blue-dark: #022734 !default;
239
+
$blue-light: #02556E !default;
240
+
$blue-50: rgba($blue-dark, 0.5) !default;
241
+
242
+
/**
243
+
* Theme variables overrides
244
+
**/
245
+
246
+
/* Colors */
247
+
$background: #fff;
248
+
$primary: lighten(#000, 13%);
249
+
250
+
```
251
+
252
+
**\_app-common.scss** file in the app template's root folder should contain any styling rules to be applied both on iOS and Android:
253
+
254
+
```CSS
255
+
/*
256
+
Place any CSS rules you want to apply on both iOS and Android here.
257
+
This is where the vast majority of your CSS code goes.
258
+
*/
259
+
260
+
/* Font icon */
261
+
.fa {
262
+
font-family: "FontAwesome";
263
+
}
264
+
265
+
/* Action bar */
266
+
.action-item,
267
+
NavigationButton {
268
+
color: $ab-color;
269
+
}
270
+
```
271
+
272
+
**app.android.scss** file in the app template's root folder should import the app variables, the NativeScript core theme main ruleset, and the common styles; also place any styling rules to be applied only on Android here:
273
+
274
+
```CSS
275
+
/* Import app variables */
276
+
@import'app-variables';
277
+
278
+
/* Import the theme's main ruleset - both index and platform specific. */
/* Place any CSS rules you want to apply only on Android here */
286
+
.action-item {
287
+
padding-right: 10;
288
+
height: 100%;
289
+
}
290
+
```
291
+
292
+
**app.ios.scss** file in the app template's root folder should import the app variables, the NativeScript core theme main ruleset, and the common styles; also place any styling rules to be applied only on iOS here:
293
+
294
+
```CSS
295
+
/* Import app variables */
296
+
@import'app-variables';
297
+
298
+
/* Import the theme’s main ruleset - both index and platform specific. */
/* Place any CSS rules you want to apply only on iOS here */
306
+
```
307
+
308
+
- Consider using the following infrastructure to enable cross-platform SASS styling on page level:
309
+
**\_[page-name]-page.scss** in the respective feature folder should contain the style rules to be applied both on iOS and Android for **[page-name]-page.ts** (e.g. if styling **cars/car-list-page.ts**, the file should be **cars/\_car-list-page.scss**):
310
+
311
+
```CSS
312
+
/* Start custom common variables */
313
+
@import'../app-variables';
314
+
/* End custom common variables */
315
+
316
+
/* Custom styles */
317
+
.list-group {
318
+
.list-group-item {
319
+
padding: 0080;
320
+
background-color: $blue-10;
321
+
322
+
.list-group-item-content {
323
+
padding: 815415;
324
+
background-color: $background-light;
325
+
}
326
+
327
+
.fa {
328
+
color: $accent-dark;
329
+
}
330
+
}
331
+
}
332
+
```
333
+
334
+
**[page-name]-page.android.scss** in the respective feature folder should contain the style rules to be applied only on Android for **[page-name]-page.ts** (e.g. if styling **cars/car-list-page.ts**, the file should be **cars/car-list-page.android.scss**):
335
+
336
+
```CSS
337
+
@import'cars-list-page';
338
+
339
+
/* Place any CSS rules you want to apply only on Android here */
340
+
```
341
+
342
+
**[page-name]-page.ios.scss** in the respective feature folder should contain the style rules to be applied only on iOS for **[page-name]-page.ts** (e.g. if styling **cars/car-list-page.ts**, the file should be **cars/car-list-page.ios.scss**):
343
+
344
+
```CSS
345
+
@import'cars-list-page';
346
+
347
+
/* Place any CSS rules you want to apply only on iOS here */
0 commit comments