Native Sheets in NativeScript

NativeScript is a mobile app framework. It builds iOS and Android apps that use JavaScript for describing layouts and events.

SheetJS is a JavaScript library for reading and writing data from spreadsheets.

This demo uses NativeScript and SheetJS to process and generate spreadsheets. We'll explore how to load SheetJS in a NativeScript app; parse and generate spreadsheets stored on the device; and fetch and parse remote files.

The "Complete Example" creates an app that looks like the screenshots below:

iOS	Android

The discussion covers the NativeScript + Angular integration. Familiarity with Angular and TypeScript is assumed.

Tested Deployments

This demo was tested in the following environments:

Simulators

OS	Device	NS	Dev Platform	Date
Android 34	Pixel 3a	8.6.1	darwin-x64	2023-12-04
iOS 17.0.1	iPhone SE (3rd gen)	8.6.1	darwin-x64	2023-12-04
Android 34	Pixel 3a	8.6.5	win10-x64	2024-04-07

Real Devices

OS	Device	NS	Date
Android 30	NVIDIA Shield	8.6.5	2024-04-07
iOS 15.1	iPad Pro	8.6.1	2023-12-04

Telemetry

Before starting this demo, manually disable telemetry.

NativeScript 8.6.1 split the telemetry into two parts: "usage" and "error". Both must be disabled separately:

npx -p nativescript ns usage-reporting disable
npx -p nativescript ns error-reporting disable

To verify telemetry was disabled:

npx -p nativescript ns usage-reporting status
npx -p nativescript ns error-reporting status

Integration Details

The SheetJS NodeJS Module can be imported from any component or script in the app.

The @nativescript/core/file-system package provides classes for file access. The File class does not support binary data, but the file access singleton from @nativescript/core does support reading and writing ArrayBuffer data.

Reading and writing data require a URL. The following snippet searches typical document folders for a specified filename:

import { Folder, knownFolders, path } from '@nativescript/core/file-system';

function get_url_for_filename(filename: string): string {
  const target: Folder = knownFolders.documents() || knownFolders.ios.sharedPublic();
  return path.normalize(target.path + "///" + filename);
}

App Configuration

Due to privacy concerns, apps must request file access. There are special APIs for accessing data and are subject to change in future platform versions.

Technical Details (click to show)

Android

Android security has evolved over the years. In newer Android versions, the following workarounds were required:

• READ_EXTERNAL_STORAGE and WRITE_EXTERNAL_STORAGE allow apps to access files outside of the app scope. These are required for scoped storage access.

When the demo was last tested, this option was enabled by default.

• android:requestLegacyExternalStorage="true" enabled legacy behavior in some older releases.

The manifest is saved to App_Resources/Android/src/main/AndroidManifest.xml:

App_Resources/Android/src/main/AndroidManifest.xml (add highlighted lines)

  <application
    android:requestLegacyExternalStorage="true"
    android:name="com.tns.NativeScriptApplication"
    android:allowBackup="true"
    android:icon="@mipmap/ic_launcher"
    android:label="@string/app_name"
    android:theme="@style/AppTheme"
    android:hardwareAccelerated="true">

• Permissions must be explicitly requested.

@nativescript-community/perms is a community module for managing permissions:

App script or component

import { request } from '@nativescript-community/perms';
import { File } from '@nativescript/core/file-system';

Storage access must be requested before writing data:

App script or component (before writing file)

  /* request permissions */
  const res = await request('storage');

The external paths can be resolved using the low-level APIs:

App script or component (writing to downloads folder)

  /* find Downloads folder */
  const dl_dir = android.os.Environment.DIRECTORY_DOWNLOADS;
  const dl = android.os.Environment.getExternalStoragePublicDirectory(dl_dir).getAbsolutePath();
  /* write to file */
  File.fromPath(dl + "/SheetJSNS.xls").writeSync(data);

Reading Local Files

getFileAccess().readBufferAsync can read data into an ArrayBuffer object. The SheetJS read method¹ can parse this data into a workbook object.²

import { getFileAccess } from '@nativescript/core';
import { read } from 'xlsx';

/* find appropriate path */
const url = get_url_for_filename("SheetJSNS.xls");

/* get data */
const ab: ArrayBuffer = await getFileAccess().readBufferAsync(url);

/* read workbook */
const wb = read(ab);

After parsing into a workbook, the sheet_to_json³ method can generate row data objects:

import { utils } from 'xlsx';

/* grab first sheet */
const wsname: string = wb.SheetNames[0];
const ws = wb.Sheets[wsname];

/* generate array of row objects */
const data = utils.sheet_to_json(ws);

Writing Local Files

The SheetJS write method⁴ with the option type: "binary" will generate Uint8Array objects. getFileAccess().writeBufferAsync can write data from a Uint8Array object to the device.

iOS supports Uint8Array directly but Android requires a true array of numbers:

import { getFileAccess } from '@nativescript/core';
import { write } from 'xlsx';

/* find appropriate path */
const url = get_url_for_filename("SheetJSNS.xls");

/* generate Uint8Array */
const u8: Uint8Array = write(wb, { bookType: 'xls', type: 'binary' });

/* attempt to save Uint8Array to file */
await getFileAccess().writeBufferAsync(url, global.isAndroid ? (Array.from(u8) as any) : u8);

A worksheet can be generated from an array of row objects with the SheetJS json_to_sheet method⁵. After generating an array, the book_new and book_append_sheet methods⁶ can create the workbook.

Fetching Remote Files

getFile from @nativescript/core/http can download files. After storing the file in a temporary folder, getFileAccess().readBufferAsync can read the data and the SheetJS read method⁷ can parse the file:

import { knownFolders, path, getFileAccess } from '@nativescript/core'
import { getFile } from '@nativescript/core/http';
import { read } from 'xlsx';

/* generate temporary path for the new file */
const temp: string = path.join(knownFolders.temp().path, "pres.xlsx");

/* download file */
const file = await getFile("https://docs.sheetjs.com/pres.xlsx", temp)

/* get data */
const ab: ArrayBuffer = await getFileAccess().readBufferAsync(file.path);

/* read workbook */
const wb = read(ab);

Complete Example

Platform Configuration

0. Disable telemetry:

npx -p nativescript ns usage-reporting disable
npx -p nativescript ns error-reporting disable

1. Follow the official Environment Setup instructions⁸.

When the demo was last tested, the latest version of the Android API was 34. NativeScript did not support that API level. The exact error message from npx -p nativescript ns doctor ios clearly stated supported versions:

✖ No compatible version of the Android SDK Build-tools are installed on your system. You can install any version in the following range: '>=23 <=33'.

The SDK Platform Android 13.0 ("Tiramisu") was compatible with NativeScript. Until NativeScript properly supports API level 34, "Tiramisu" must be used. This requires installing the following packages from Android Studio:

• Android 13.0 ("Tiramisu") API Level 33
• Android SDK Build-Tools Version 33.0.2

2. Test the local system configuration for Android development:

npx -p nativescript ns doctor android

In the last macOS test, the following output was displayed:

Expected output (click to hide)

✔ Getting environment information
No issues were detected.
✔ Your ANDROID_HOME environment variable is set and points to correct directory.
✔ Your adb from the Android SDK is correctly installed.
✔ The Android SDK is installed.
✔ A compatible Android SDK for compilation is found.
✔ Javac is installed and is configured properly.
✔ The Java Development Kit (JDK) is installed and is configured properly.
✔ Getting NativeScript components versions information...
✔ Component nativescript has 8.6.1 version and is up to date.

3. Test the local system configuration for iOS development (macOS only):

npx -p nativescript ns doctor ios

In the last macOS test, the following output was displayed:

Expected output (click to hide)

✔ Getting environment information
No issues were detected.
✔ Xcode is installed and is configured properly.
✔ xcodeproj is installed and is configured properly.
✔ CocoaPods are installed.
✔ CocoaPods update is not required.
✔ CocoaPods are configured properly.
✔ Your current CocoaPods version is newer than 1.0.0.
✔ Python installed and configured correctly.
✔ The Python 'six' package is found.
✔ Xcode version 15.0.1 satisfies minimum required version 10.
✔ Getting NativeScript components versions information...
✔ Component nativescript has 8.6.1 version and is up to date.

Base Project

4. Create a skeleton NativeScript + Angular app:

npx -p nativescript ns create SheetJSNS --ng

5. Launch the app in the android simulator to verify the app:

cd SheetJSNS
npx -p nativescript ns run android

(this may take a while)

Once the simulator launches and the test app is displayed, end the script by selecting the terminal and pressing CTRL+C. On Windows, if prompted to Terminate batch job, type y and press Enter.

If the emulator is not running, nativescript may fail with the message:

Emulator start failed with: No emulator image available for device identifier 'undefined'.

Add SheetJS

The goal of this section is to display the SheetJS library version number.

6. From the project folder, install the SheetJS NodeJS module:

npm i --save https://cdn.sheetjs.com/xlsx-0.20.2/xlsx-0.20.2.tgz

7. Edit src/app/item/items.component.ts so that the component imports the SheetJS version string and adds it to a version variable in the component:

src/app/item/items.component.ts (add highlighted lines)

import { version } from 'xlsx';
import { Component, OnInit } from '@angular/core'

// ...

export class ItemsComponent implements OnInit {
  items: Array<Item>
  version = `SheetJS - ${version}`;

  constructor(private itemService: ItemService) {}
// ...

8. Edit the template src/app/item/items.component.html to reference version in the title of the action bar:

src/app/item/items.component.html (edit highlighted line)

<ActionBar [title]="version"></ActionBar>

<GridLayout>
<!-- ... -->

9. End the script and relaunch the app in the Android simulator:

npx -p nativescript ns run android

The title bar should show the version.

Local Files

10. Add the Import and Export buttons to the template:

src/app/item/items.component.html (add highlighted lines)

<ActionBar [title]="version"></ActionBar>

<StackLayout>
  <StackLayout orientation="horizontal">
    <Button text="Import File" (tap)="import()" style="padding: 10px"></Button>
    <Button text="Export File" (tap)="export()" style="padding: 10px"></Button>
  </StackLayout>
  <ListView [items]="items">
    <!-- ... -->
  </ListView>
</StackLayout>

11. Add the import and export methods in the component script:

src/app/item/items.component.ts

import { version, utils, read, write } from 'xlsx';
import { Dialogs, getFileAccess } from '@nativescript/core';
import { Folder, knownFolders, path } from '@nativescript/core/file-system';
import { Component, OnInit } from '@angular/core'

import { Item } from './item'
import { ItemService } from './item.service'

function get_url_for_filename(filename: string): string {
  const target: Folder = knownFolders.documents() || knownFolders.ios.sharedPublic();
  return path.normalize(target.path + "///" + filename);
}

@Component({
  selector: 'ns-items',
  templateUrl: './items.component.html',
})
export class ItemsComponent implements OnInit {
  items: Array<Item>
  version: string = `SheetJS - ${version}`;

  constructor(private itemService: ItemService) {}

  ngOnInit(): void {
    this.items = this.itemService.getItems()
  }

  /* Import button */
  async import() {
  }

  /* Export button */
  async export() {
  }
}

12. End the script and relaunch the app in the Android simulator:

npx -p nativescript ns run android

Two buttons should appear just below the header:

13. Implement import and export by adding the highlighted lines:

src/app/item/items.component.ts (add highlighted lines)

  /* Import button */
  async import() {
    /* find appropriate path */
    const url = get_url_for_filename("SheetJSNS.xls");

    try {
      await Dialogs.alert(`Attempting to read from SheetJSNS.xls at ${url}`);
      /* get data */
      const ab: ArrayBuffer = await getFileAccess().readBufferAsync(url);

      /* read workbook */
      const wb = read(ab);

      /* grab first sheet */
      const wsname: string = wb.SheetNames[0];
      const ws = wb.Sheets[wsname];

      /* update table */
      this.items = utils.sheet_to_json<Item>(ws);
    } catch(e) { await Dialogs.alert(e.message); }
  }

  /* Export button */
  async export() {
    /* find appropriate path */
    const url = get_url_for_filename("SheetJSNS.xls");

    try {
      /* create worksheet from data */
      const ws = utils.json_to_sheet(this.items);

      /* create workbook from worksheet */
      const wb = utils.book_new();
      utils.book_append_sheet(wb, ws, "Sheet1");

      /* generate Uint8Array */
      const u8: Uint8Array = write(wb, { bookType: 'xls', type: 'buffer' });

      /* attempt to save Uint8Array to file */
      await getFileAccess().writeBufferAsync(url, global.isAndroid ? (Array.from(u8) as any) : u8);
      await Dialogs.alert(`Wrote to SheetJSNS.xls at ${url}`);
    } catch(e) { await Dialogs.alert(e.message); }
  }

Android

14. Launch the app in the Android Simulator:

npx -p nativescript ns run android

If the app does not automatically launch, manually open the SheetJSNS app.

15. Tap "Export File". A dialog will print where the file was written. Typically the URL is /data/user/0/org.nativescript.SheetJSNS/files/SheetJSNS.xls

16. Pull the file from the simulator. The following commands should be run in a new terminal or PowerShell window:

adb root
adb pull /data/user/0/org.nativescript.SheetJSNS/files/SheetJSNS.xls SheetJSNS.xls

If the emulator cannot be rooted, the following command works in macOS:

adb shell "run-as org.nativescript.SheetJSNS cat /data/user/0/org.nativescript.SheetJSNS/files/SheetJSNS.xls" > SheetJSNS.xls

17. Open SheetJSNS.xls with a spreadsheet editor.

After the header row, insert a row with cell A2 = 0, B2 = SheetJS, C2 = Library:

id | name       | role
 0 | SheetJS    | Library
 1 | Ter Stegen | Goalkeeper
 3 | Piqué      | Defender
...

18. Push the file back to the simulator:

adb push SheetJSNS.xls /data/user/0/org.nativescript.SheetJSNS/files/SheetJSNS.xls

If the emulator cannot be rooted, the following command works in macOS:

dd if=SheetJSNS.xls | adb shell "run-as org.nativescript.SheetJSNS dd of=/data/user/0/org.nativescript.SheetJSNS/files/SheetJSNS.xls"

19. Tap "Import File". A dialog will print the path of the file that was read. The first item in the list will change.

iOS

iOS testing can only be performed on Apple hardware running macOS!

Xcode and iOS simulators are not available on Windows or Linux.

Scroll down to "Fetching Files" for Android device testing.

20. Launch the app in the iOS Simulator:

npx -p nativescript ns run ios

21. Tap "Export File". A dialog will print where the file was written.

22. Open the file with a spreadsheet editor.

After the header row, insert a row with cell A2 = 0, B2 = SheetJS, C2 = Library:

id | name       | role
 0 | SheetJS    | Library
 1 | Ter Stegen | Goalkeeper
 3 | Piqué      | Defender
...

23. Restart the app after saving the file.

24. Tap "Import File". A dialog will print the path of the file that was read. The first item in the list will change:

Fetching Files

25. In src/app/item/items.component.ts, make ngOnInit asynchronous:

src/app/item/items.component.ts (replace existing function)

  async ngOnInit(): Promise<void> {
    this.items = await this.itemService.getItems()
  }

26. Replace item.service.ts with the following:

src/app/item/item.service.ts

import { Injectable } from '@angular/core'

import { knownFolders, path, getFileAccess } from '@nativescript/core'
import { getFile } from '@nativescript/core/http';
import { read, utils  } from 'xlsx';

import { Item } from './item'
interface IPresident { Name: string; Index: number };

@Injectable({ providedIn: 'root' })
export class ItemService {
  private items: Array<Item>;

  async getItems(): Promise<Array<Item>> {
    /* fetch https://docs.sheetjs.com/pres.xlsx */
    const temp: string = path.join(knownFolders.temp().path, "pres.xlsx");
    const ab = await getFile("https://docs.sheetjs.com/pres.xlsx", temp)
    /* read the temporary file */
    const wb = read(await getFileAccess().readBufferAsync(ab.path));
    /* translate the first worksheet to the required Item type */
    const data = utils.sheet_to_json<IPresident>(wb.Sheets[wb.SheetNames[0]]);
    return this.items = data.map((pres, id) => ({id, name: pres.Name, role: ""+pres.Index} as Item));
  }

  getItem(id: number): Item {
    return this.items.filter((item) => item.id === id)[0]
  }
}

27. End the script and relaunch the app in the Android simulator:

npx -p nativescript ns run android

The app should show Presidential data.

Android Device

28. Connect an Android device using a USB cable.

If the device asks to allow USB debugging, tap "Allow".

29. Close any Android / iOS emulators.

30. Enable "Legacy External Storage" in the Android app. The manifest is stored at App_Resources/Android/src/main/AndroidManifest.xml:

App_Resources/Android/src/main/AndroidManifest.xml (add highlighted line)

  <application
    android:requestLegacyExternalStorage="true"
    android:name="com.tns.NativeScriptApplication"
    android:allowBackup="true"
    android:icon="@mipmap/ic_launcher"
    android:label="@string/app_name"
    android:theme="@style/AppTheme"
    android:hardwareAccelerated="true">

31. Install the @nativescript-community/perms dependency:

npm i --save @nativescript-community/perms

32. Add the highlighted lines to items.component.ts:

• Import File from NativeScript core and request from the new dependency:

items.component.ts (add highlighted lines)

import { Dialogs, getFileAccess, Utils } from '@nativescript/core';
import { request } from '@nativescript-community/perms';
import { Folder, knownFolders, path, File } from '@nativescript/core/file-system';
import { Component, OnInit } from '@angular/core'
// ...

• Add a new write operation to the export method:

items.component.ts (add highlighted lines)

      /* attempt to save Uint8Array to file */
      await getFileAccess().writeBufferAsync(url, global.isAndroid ? (Array.from(u8) as any) : u8);
      await Dialogs.alert(`Wrote to SheetJSNS.xls at ${url}`);

      if(global.isAndroid) {
        /* request permissions */
        const res = await request('storage');
        /* write to Downloads folder */
        const dl = android.os.Environment.getExternalStoragePublicDirectory(android.os.Environment.DIRECTORY_DOWNLOADS).getAbsolutePath();
        File.fromPath(dl + "/SheetJSNS.xls").writeSync(Array.from(u8));
      }
    } catch(e) { await Dialogs.alert(e.message); }

33. Build APK and run on device:

npx -p nativescript ns run android

If the Android emulators are closed and an Android device is connected, the last command will build an APK and install on the device.

Android Device Testing (click to hide)

When the app launches, if the SheetJS library is loaded and if the device is connected to the Internet, a list of Presidents should be displayed.

Tap "Export File". The app will show an alert. Tap "OK".

Switch to the "Files" app and open the "Downloads" folder. There should be a new file named SheetJSNS.xls.

iOS Device

34. Connect an iOS device using a USB cable

35. Close any Android / iOS emulators.

36. Enable developer code signing certificates⁹

37. Run on device:

npx -p nativescript ns run ios

Footnotes

1. See read in "Reading Files" ↩

2. See "Workbook Object" ↩

3. See sheet_to_json in "Utilities" ↩

4. See write in "Writing Files" ↩

5. See json_to_sheet in "Utilities" ↩

6. See "Workbook Helpers" in "Utilities" for details on book_new and book_append_sheet. ↩

7. See read in "Reading Files" ↩

8. See "Local setup" in the NativeScript documentation. For Windows and Linux, follow the "Android" instructions. For macOS, follow both the iOS and Android instructions. ↩

9. The Flutter documentation covers the instructions in more detail. The correct workspace is platforms/ios/SheetJSNS.xcodeproj/project.xcworkspace ↩