{"id":20846746,"url":"https://github.com/kimgoetzke/listem","last_synced_at":"2025-05-09T03:17:44.730Z","repository":{"id":224403713,"uuid":"758994082","full_name":"kimgoetzke/listem","owner":"kimgoetzke","description":"A minimalist list app for Android, written in C# using .NET MAUI.","archived":false,"fork":false,"pushed_at":"2024-07-06T09:59:14.000Z","size":7244,"stargazers_count":3,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-05-09T03:17:34.586Z","etag":null,"topics":["android","csharp","dotnet","maui","maui-app","sqlite"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kimgoetzke.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-02-17T17:14:06.000Z","updated_at":"2024-06-25T17:40:49.000Z","dependencies_parsed_at":"2024-06-25T10:11:43.177Z","dependency_job_id":null,"html_url":"https://github.com/kimgoetzke/listem","commit_stats":null,"previous_names":["kimgoetzke/practice-maui-listem","kimgoetzke/listem"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kimgoetzke%2Flistem","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kimgoetzke%2Flistem/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kimgoetzke%2Flistem/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kimgoetzke%2Flistem/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kimgoetzke","download_url":"https://codeload.github.com/kimgoetzke/listem/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253181442,"owners_count":21866995,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","csharp","dotnet","maui","maui-app","sqlite"],"created_at":"2024-11-18T02:17:48.239Z","updated_at":"2025-05-09T03:17:44.695Z","avatar_url":"https://github.com/kimgoetzke.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# The Listem Project with MongoDB Atlas and Realm\n\nThis repository contains a super simple, minimalist list Android app written in C# using .NET 8 MAUI, the\nCommunityToolkit, and MongoDB Atlas with Realm and Flexible Sync. It also contains a UI test project for end-to-end\ntesting using Appium and NUnit 4. It was created to learn how to create and publish an Android app.\n\n![Screenshots](./docs/assets/screenshots.png)\n\n### Overview\n\n- A super basic, minimalist app for lists, targeting Android\n- Users can register and log in without requiring an email address (only a username and password are needed)\n- Users can share lists with other users through the app and collaborate on them\n- Lists can be somewhat customised by adding categories or list types (e.g. changing type to shopping list exposes a\n  quantity control in the UI)\n- A list's content can be exported to the clipboard as text\n- List items can be imported from a comma-separated string from the clipboard and merged with the current list\n- Native confirmation prompts are used for destructive actions\n- The app features a light theme (default) and an initial dark theme\n- Icons used are CC0 from [iconsDB.com](https://www.iconsdb.com/) or self-made\n- Colour scheme and topography inspired by Mailin\n  Hülsmann's [Tennis App - UX/UI Design Case Study](https://www.behance.net/gallery/124361333/Tennis-App-UXUI-Design-Case-Study)\n\n![More screenshots](./docs/assets/screenshots_2.png)\n\n### How to configure your environment for development\n\n\u003e [!NOTE]  \n\u003e I explored creating an ASP.NET Core backend (see\n\u003e branch [use-backend-api](https://github.com/kimgoetzke/listem/tree/use-backend-api)) but I didn't find\n\u003e an easy solution to deal with data synchronisation and conflict management (e.g. offline vs online changes, especially\n\u003e to shared lists). This eventually led me to implement MongoDB Atlas with Realm and Flexible Sync because it allows\n\u003e for offline-first development, deals with conflict resolution, and even offers authorisation/authentication.\n\n1. Set environment variables for builds and running tests\n    1. `ANDROID_HOME` - the absolute path of the Android SDK\n    2. `LISTEM_DEBUG_APK` - the absolute path of the debug APK, used by UI tests only\n    3. `LISTEM_RELEASE_APK` - the absolute path of the release APK, used by UI tests only\n    4. `ANDROID_KEY_PASS` - the password for the keystore used to sign the APK\n    5. `ANDROID_STORE_PASS` - the password for the key used to sign the APK\n2. Run `dotnet restore` in the base directory to restore all dependencies\n\n### How to build the APK\n\nCreate APK with:\n\n```shell\ncd Listem.Mobile ; dotnet publish -f:net8.0-android -c:Release /p:AndroidSdkDirectory=$env:ANDROID_HOME\n```\n\nThis assumes that the Android SDK is installed and the `ANDROID_HOME` environment variable is set.\n\nAPK file can then be found in `ShoppingList\\bin\\Release\\net8.0-android\\publish\\` and installed directly on any Android\nphone.\n\n### How to publish the app to the Google Play Store\n\n1. Create a keystore\n   with e.g. `keytool -genkey -v -keystore listem.keystore -alias listem -keyalg RSA -keysize 2048 -validity 10000` and\n   set\n   the password as environment variable(s) accordingly\n2. Publish and sign the app:\n    ```shell\n    cd Listem.Mobile ; dotnet publish -f:net8.0-android -c:Release /p:AndroidSdkDirectory=$env:ANDROID_HOME /p:AndroidSigningKeyPass=$env:ANDROID_KEY_PASS /p:AndroidSigningStorePass=$env:ANDROID_STORE_PASS\n    ```\n3. Follow the usual steps to upload to the Google Play Console e.g.\n   see [Microsoft - Publish a .NET MAUI app for Android](https://learn.microsoft.com/en-us/dotnet/maui/android/deployment/?view=net-maui-8.0)\n\n### How to run UI tests\n\n\u003e [!NOTE]  \n\u003e I am unable to get Appium to install the APK correctly on the device/emulator. It appears the app is corrupted when\n\u003e doing this. That's why, to run the tests, you need to install the APK on the device/emulator yourself before running\n\u003e the tests. If the APK is ever installed by Appium, the device needs to be wiped and the APK installed again without\n\u003e Appium for the app to get beyond the splash screen.\n\nPrerequisites:\n\n1. Install Appium, e.g. with `npm i -g appium`\n2. Install an Appium Android driver: `appium driver install uiautomator2`\n\nTo run the tests:\n\n1. Install the APK on the device/emulator\n2. Navigate to the `Listem.UITests` project with `cd Listem.UITests`\n3. Run the tests via your IDE or with `dotnet test`\n\nFor building any further tests, consider installing [Appium Inspector](https://github.com/appium/appium-inspector) in\norder to debug elements. Run Appium with `appium` and open the inspector, using the following config to connect to a\nrunning session:\n\n```json\n{\n  \"platformName\": \"Android\",\n  \"appium:automationName\": \"UiAutomator2\"\n}\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkimgoetzke%2Flistem","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkimgoetzke%2Flistem","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkimgoetzke%2Flistem/lists"}