0
# NativeScript Core Modules
1

2
NativeScript Core Modules (`tns-core-modules`) is a compatibility package that provides the complete NativeScript framework API for building native iOS and Android mobile applications using JavaScript, TypeScript, and CSS. It delivers true native performance without WebViews by bridging JavaScript to native APIs, enabling access to platform-specific functionality through unified cross-platform interfaces.
3

4
## Package Information
5

6
- **Package Name**: tns-core-modules
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install tns-core-modules`
10

11
## Core Imports
12

13
```typescript
14
// Application lifecycle and utilities
15
import { Application, ApplicationSettings } from "tns-core-modules";
16

17
// UI components and layouts
18
import { Page, StackLayout, Button, Label } from "tns-core-modules";
19

20
// Data handling
21
import { Observable, ObservableArray } from "tns-core-modules";
22

23
// File system and HTTP
24
import { File, Folder, Http } from "tns-core-modules";
25

26
// Performance monitoring and debugging
27
import { Profiling, Trace } from "tns-core-modules";
28

29
// Utility functions and platform services
30
import { Utils, Connectivity, Color } from "tns-core-modules";
31

32
// XML parsing
33
import { XmlParser, ParserEventType } from "tns-core-modules";
34
```
35

36
For CommonJS:
37

38
```javascript
39
const { Application, Page, Button } = require("tns-core-modules");
40
```
41

42
## Basic Usage
43

44
```typescript
45
import { Application, Page, StackLayout, Button, Label } from "tns-core-modules";
46

47
// Application setup
48
Application.run({ moduleName: "main-page" });
49

50
// Create a simple page with UI
51
export function createPage() {
52
  const page = new Page();
53
  const stack = new StackLayout();
54
  
55
  const label = new Label();
56
  label.text = "Hello NativeScript!";
57
  
58
  const button = new Button();
59
  button.text = "Click Me";
60
  button.on("tap", () => {
61
    label.text = "Button tapped!";
62
  });
63
  
64
  stack.addChild(label);
65
  stack.addChild(button);
66
  page.content = stack;
67
  
68
  return page;
69
}
70
```
71

72
## Architecture
73

74
NativeScript Core Modules provides several key architectural components:
75

76
- **Application Layer**: Lifecycle management, navigation, and app-wide utilities
77
- **UI Framework**: 30+ native UI components with cross-platform abstractions
78
- **Data Binding**: Observable pattern with two-way data binding capabilities
79
- **Platform Services**: File system, HTTP client, device APIs, and system integrations
80
- **Styling System**: CSS-like styling with platform-specific adaptations
81
- **Native Bridge**: Direct access to iOS and Android native APIs
82

83
## Capabilities
84

85
### Application Management
86

87
Core application lifecycle, navigation, and configuration management for NativeScript apps.
88

89
```typescript { .api }
90
namespace Application {
91
  // Application lifecycle events
92
  const launchEvent: string;
93
  const suspendEvent: string;
94
  const resumeEvent: string;
95
  const exitEvent: string;
96
  
97
  // Core application functions
98
  function run(entry?: any): void;
99
  function getRootView(): View;
100
  function orientation(): string;
101
  function hasLaunched(): boolean;
102
  
103
  // Platform-specific instances
104
  const android: AndroidApplication;
105
  const ios: iOSApplication;
106
}
107

108
namespace ApplicationSettings {
109
  function setString(key: string, value: string): void;
110
  function getString(key: string, defaultValue?: string): string;
111
  function setBoolean(key: string, value: boolean): void;
112
  function getBoolean(key: string, defaultValue?: boolean): boolean;
113
  function clear(): void;
114
}
115
```
116

117
[Application Management](./application.md)
118

119
### UI Components and Layouts
120

121
Comprehensive set of native UI components including buttons, labels, inputs, and advanced controls like lists and navigation.
122

123
```typescript { .api }
124
// Core UI base classes
125
class ViewBase {
126
  id: string;
127
  className: string;
128
  style: Style;
129
  parent: ViewBase;
130
  isLoaded: boolean;
131
  
132
  on(eventName: string, callback: Function): void;
133
  off(eventName: string, callback?: Function): void;
134
}
135

136
class View extends ViewBase {
137
  width: number | string;
138
  height: number | string;
139
  visibility: string;
140
  opacity: number;
141
}
142

143
// Layout containers
144
class StackLayout extends LayoutBase {
145
  orientation: string;
146
}
147

148
class GridLayout extends LayoutBase {
149
  columns: string;
150
  rows: string;
151
}
152

153
// UI controls
154
class Button extends View {
155
  text: string;
156
  tap: string; // event name
157
}
158

159
class Label extends View {
160
  text: string;
161
  textWrap: boolean;
162
}
163
```
164

165
[UI Components](./ui-components.md)
166

167
### Data Binding and Observables
168

169
Reactive data handling with Observable pattern supporting two-way data binding and change notifications.
170

171
```typescript { .api }
172
class Observable {
173
  constructor(obj?: any);
174
  
175
  get(name: string): any;
176
  set(name: string, value: any): void;
177
  on(eventName: string, callback: Function): void;
178
  off(eventName: string, callback?: Function): void;
179
  notify(data: PropertyChangeData): void;
180
}
181

182
class ObservableArray<T> extends Array<T> {
183
  constructor(...items: T[]);
184
  
185
  push(...items: T[]): number;
186
  pop(): T;
187
  splice(start: number, deleteCount?: number, ...items: T[]): T[];
188
  
189
  on(eventName: string, callback: Function): void;
190
}
191

192
interface PropertyChangeData {
193
  object: Observable;
194
  propertyName: string;
195
  value: any;
196
  oldValue: any;
197
}
198
```
199

200
[Data Binding](./data-binding.md)
201

202
### File System Operations
203

204
Cross-platform file system access for reading, writing, and managing files and folders on mobile devices.
205

206
```typescript { .api }
207
class File extends FileSystemEntity {
208
  static fromPath(path: string): File;
209
  
210
  readText(encoding?: string): Promise<string>;
211
  writeText(content: string, encoding?: string): Promise<void>;
212
  readTextSync(encoding?: string): string;
213
  writeTextSync(content: string, encoding?: string): void;
214
}
215

216
class Folder extends FileSystemEntity {
217
  static fromPath(path: string): Folder;
218
  
219
  getFile(name: string): File;
220
  getFolder(name: string): Folder;
221
  getEntities(): Promise<FileSystemEntity[]>;
222
  eachEntity(onEntity: Function): void;
223
}
224

225
namespace knownFolders {
226
  const documents: Folder;
227
  const temp: Folder;
228
  const currentApp: Folder;
229
}
230
```
231

232
[File System](./file-system.md)
233

234
### HTTP Client
235

236
Full-featured HTTP client for REST API calls, file downloads, and network communication.
237

238
```typescript { .api }
239
namespace Http {
240
  function request(options: HttpRequestOptions): Promise<HttpResponse>;
241
  function getJSON<T>(url: string): Promise<T>;
242
  function getString(url: string): Promise<string>;
243
  function getFile(url: string, destinationFilePath?: string): Promise<File>;
244
  function getImage(url: string): Promise<ImageSource>;
245
}
246

247
interface HttpRequestOptions {
248
  url: string;
249
  method?: string;
250
  headers?: any;
251
  content?: string | any;
252
  timeout?: number;
253
}
254

255
interface HttpResponse {
256
  statusCode: number;
257
  content: HttpContent;
258
  headers: any;
259
}
260
```
261

262
[HTTP Client](./http-client.md)
263

264
### Image Handling
265

266
Comprehensive image loading, manipulation, and caching capabilities for mobile applications.
267

268
```typescript { .api }
269
class ImageSource {
270
  static fromFile(path: string): ImageSource;
271
  static fromData(data: any): ImageSource;
272
  static fromBase64(source: string): ImageSource;
273
  
274
  saveToFile(path: string, format: string, quality?: number): boolean;
275
  toBase64String(format: string, quality?: number): string;
276
}
277

278
class ImageAsset {
279
  constructor(asset: any);
280
  
281
  getImage(options?: ImageAssetOptions): Promise<ImageSource>;
282
}
283

284
interface ImageAssetOptions {
285
  maxWidth?: number;
286
  maxHeight?: number;
287
  aspectRatio?: string;
288
  autoScaleFactor?: boolean;
289
}
290
```
291

292
[Image Handling](./image-handling.md)
293

294
### Platform Utilities
295

296
Device information, platform detection, and native utility functions for iOS and Android integration.
297

298
```typescript { .api }
299
// Platform detection
300
function isAndroid(): boolean;
301
function isIOS(): boolean;
302

303
// Device information
304
interface Device {
305
  model: string;
306
  deviceType: string;
307
  os: string;
308
  osVersion: string;
309
  sdkVersion: string;
310
  language: string;
311
  region: string;
312
}
313

314
// Screen information  
315
interface Screen {
316
  mainScreen: ScreenMetrics;
317
  widthDIPs: number;
318
  heightDIPs: number;
319
  scale: number;
320
}
321

322
// Utility functions
323
namespace Utils {
324
  function executeOnMainThread(func: Function): void;
325
  function isMainThread(): boolean;
326
  function openUrl(url: string): boolean;
327
  function openFile(filePath: string): boolean;
328
}
329
```
330

331
[Platform Utilities](./platform-utils.md)
332

333
### Performance Profiling
334

335
Performance monitoring and profiling tools for measuring method execution times, memory usage, and application performance metrics.
336

337
```typescript { .api }
338
namespace Profiling {
339
  // Core profiling controls
340
  function enable(type?: InstrumentationMode): void;
341
  function disable(): void;
342
  function isRunning(name: string): boolean;
343
  
344
  // Timer functions
345
  function time(): number;
346
  function uptime(): number;
347
  function start(name: string): void;
348
  function stop(name: string): TimerInfo;
349
  
350
  // Profile management
351
  function dumpProfiles(): void;
352
  function resetProfiles(): void;
353
  function profile(name?: string): MethodDecorator;
354
  function profile<F extends Function>(fn: F): F;
355
  function profile<F extends Function>(name: string, fn: F): F;
356
  
357
  // CPU profiling (Android)
358
  function startCPUProfile(name: string): void;
359
  function stopCPUProfile(name: string): void;
360
}
361

362
type InstrumentationMode = "counters" | "timeline" | "lifecycle";
363

364
interface TimerInfo {
365
  totalTime: number;
366
  count: number;
367
}
368
```
369

370
### Debug Tracing
371

372
Debug tracing and logging system with category-based filtering and multiple output writers for comprehensive application debugging.
373

374
```typescript { .api }
375
namespace Trace {
376
  // Core trace controls
377
  function enable(): void;
378
  function disable(): void;
379
  function isEnabled(): boolean;
380
  
381
  // Writer management
382
  function addWriter(writer: TraceWriter): void;
383
  function removeWriter(writer: TraceWriter): void;
384
  function clearWriters(): void;
385
  
386
  // Category management
387
  function setCategories(categories: string): void;
388
  function addCategories(categories: string): void;
389
  
390
  // Logging functions
391
  function write(message: any, category: string, type?: number): void;
392
  function error(error: string | Error): void;
393
  
394
  // Event handling
395
  function setErrorHandler(handler: ErrorHandler): void;
396
  
397
  // Predefined categories
398
  const categories: {
399
    VisualTreeEvents: string;
400
    Layout: string;
401
    Style: string;
402
    ViewHierarchy: string;
403
    NativeLifecycle: string;
404
    Debug: string;
405
    Navigation: string;
406
    Test: string;
407
    Binding: string;
408
    Error: string;
409
    Animation: string;
410
    Transition: string;
411
    All: string;
412
  };
413
  
414
  // Message types
415
  const messageType: {
416
    log: number;
417
    info: number;
418
    warn: number;
419
    error: number;
420
  };
421
}
422

423
interface TraceWriter {
424
  write(message: any, category: string, type?: number): void;
425
}
426

427
interface ErrorHandler {
428
  handlerError(error: Error): void;
429
}
430
```
431

432
### Network Connectivity
433

434
Network connection monitoring and detection capabilities for managing network-dependent application behavior.
435

436
```typescript { .api }
437
namespace Connectivity {
438
  // Connection detection
439
  function getConnectionType(): number;
440
  function startMonitoring(callback: (newConnectionType: number) => void): void;
441
  function stopMonitoring(): void;
442
  
443
  // Connection types
444
  const connectionType: {
445
    none: 0;
446
    wifi: 1;
447
    mobile: 2;
448
    ethernet: 3;
449
    bluetooth: 4;
450
    vpn: 5;
451
  };
452
}
453
```
454

455
### Color Management
456

457
Color creation and manipulation utilities supporting multiple color formats and platform-specific representations.
458

459
```typescript { .api }
460
class Color {
461
  constructor(knownColor: string);
462
  constructor(hex: string);
463
  constructor(argb: number);
464
  constructor(alpha: number, red: number, green: number, blue: number);
465
  
466
  // Color components (read-only)
467
  readonly a: number; // Alpha (0-255)
468
  readonly r: number; // Red (0-255)
469
  readonly g: number; // Green (0-255)
470
  readonly b: number; // Blue (0-255)
471
  
472
  // Color representations (read-only)
473
  readonly hex: string;
474
  readonly argb: number;
475
  readonly name: string;
476
  readonly android: number;
477
  readonly ios: any; // UIColor
478
  
479
  // Utility methods
480
  equals(value: Color): boolean;
481
  static equals(value1: Color, value2: Color): boolean;
482
  static isValid(value: any): boolean;
483
}
484
```
485

486
### XML Parsing
487

488
SAX-based XML parsing with event-driven processing and namespace support for handling XML data and documents.
489

490
```typescript { .api }
491
class XmlParser {
492
  constructor(
493
    onEvent: (event: ParserEvent) => void,
494
    onError?: (error: Error, position: Position) => void,
495
    processNamespaces?: boolean,
496
    angularSyntax?: boolean
497
  );
498
  
499
  parse(xmlString: string): void;
500
}
501

502
class ParserEventType {
503
  static StartElement: string;
504
  static EndElement: string;
505
  static Text: string;
506
  static CDATA: string;
507
  static Comment: string;
508
}
509

510
interface ParserEvent {
511
  eventType: string;
512
  position: Position;
513
  prefix?: string;
514
  namespace?: string;
515
  elementName?: string;
516
  attributes?: any;
517
  data?: string;
518
  toString(): string;
519
}
520

521
interface Position {
522
  line: number;
523
  column: number;
524
}
525
```