Wikistreets Nativescript Client

Native mobile app developed with Nativescript, Svelte, and TailwindCSS.

Projects that make this possible

OpenStreetMap data

This app depends upon OpenStreetMap (OSM) data, © OpenStreetMap contibutors, and made available for use under the Open Database License. If you notice any map data that should be updated or corrected, consider fixing it yourself or reporting the issue.

OpenStreetMap map tiles

By default, we also use the OSM tile server, in accordance with their Tile Usage Policy. This tile server is entirely supported by donations and not meant to be used heavily by apps. Consider donating to OSM to support their mission to make map data and map image tiles freely available to the world. Should our app become so popular that we exceed their very reasonable tile usage limits, we have provided an in-app account setting that allows users to switch to a different tile server.

Alternate tile servers

OpenStreetMap maintains a list of raster and vector tile providers that can be used within the app in place of the default OSM standard tile server.

Installation

• create Apple Developer account at https://developer.apple.com/
• install XCode and Android Studio
• set up environment according to instructions
• install nativescript: npm install -g nativescript
• install dependencies: npm install
• ensure that tailwindcss is at version 3.1.8, since later versions are currently incompatible
• create an .env file based on the env.example with correct values for each variable
• run the app in debug mode in simulator: ns debug ios or ns debug android
• run the app without debugging in simulator: ns run ios or ns run android
• run the app on a physical device - see details

Camera permissions

The app uses the camera plugin - follow the setup instructions there to grant permissions to the camera on both Android and iOS.

GPS permissions

It may be necessary to grant permission to use the device's GPS. I haven't thoroughly tested this yet.

Testing

The project is set up to run unit tests using jasmine. Tests should be placed in the app/tests directory. Run them with ns test ios or ns test android. Optional flags include --emulator to launch the tests within the device emulator, --justlaunch to quit the emulator once tests are complete, and --watch to re-launch the tests automatically upon code change.

Troubleshooting

Hot Module Reloading (HMR)

If running on iOS shows error messages mentioning hmr, try running without that, e.g. ns debug ios --no-hmr. This isn't a solution, since HMR should work, but could avoid the problem.

Android

If running on Android produces errors about Duplicate class in Kotlin, follow the solution mentioned here and insert the following line into the platforms/android/app/build.gradle at the bottom of the dependencies { ... } code block:

implementation(platform("org.jetbrains.kotlin:kotlin-bom:1.8.0"))

Documentation

Nativescript and Svelte Native are woefully underdocumented. However, here are a few useful links:

• My own notes on using Svelte and Nativescript.
• Nativescript v7 documentation, while out of date, contains the most thorough documentation of the basic concepts of Nativescript development.
• Nativescript v8 documentation, while useful and up to date, does a poor job explaining some fundamental concepts.
• Svelte Native documentation provides some simple notes about getting started with Svelte and Nativescript.
• Svelte documentation, while focused on web apps, is useful in understanding Svelte props, stores, and other core features.
• Nativescript Community Plugins - extensions that provide common functionality.
• iOS system icons - their integer values can be used in actionItem components with the ios.systemIcon attribute.
• Android system icons - the names can be used in actionItem components with the android.systemIcon attribute.

Toolkit

Built with almost entirely open source platforms and tools, including but not limited to:

• Nativescript for cross-platform mobile development
• Svelte as the front-end framework
• TailwindCSS for styling
• Map data from OpenStreetMap
• Maps presented by Leaflet
• Visual Studio Code as the IDE

Icons:

• App widget icons generated by IconKitchen
• Navigation icons by Material Design Iconic Font
• Additional icons may be sourced from SJJB SVG Map Icons and/or icons8

Useful reading/watching

Svelte

• 6 Ways to Do Component Communications in Svelte
• How Svelte Stores Make State Management Easy

Leaflet

• Using SVG icons for Leaflet js markers

Nativescript

• useful plugins by nativescript, nativescript-community, and plugins by triniwiz
• CollectionView plugin: yarn documentation and Harness the power of CollectionView
• Filterable List Picker in NativeScript
• Animated Bottom Sheet in NativeScript Tutorial