[RFC] Actual mobile strategy

[trevdor]

Verified feature request does not already exist?

• I have searched and found no existing issue

💻

• Would you like to implement this feature?

Pitch: what problem are you trying to solve?

RFC: Actual Mobile Strategy

Note: Throughout, I’ll use the terms “desktop” and “mobile” as shorthand for wide vs narrow viewports. It’s just a convenience. The switch could just as easily be based available screen width, and in any case, a preference could be stored to allow folks to set a preferred view independent of device or viewport. But all that is a separate discussion.

Purpose of this Document

1. Identify what mobile support means for Actual so we can all build in a unified direction
2. Establish methods for separating the distinct aspects of desktop and mobile views
3. Identify features that contributors could tackle next

Mobile Support Goals

A. On mobile, Actual will focus on the most common budgeting tasks and on-the-go transaction entry and editing. Some extended budgeting features will be limited to the desktop version.

B. Actual should feel like a native app whenever possible. Besides look and feel (app icon, styling, page transitions, etc.), it should leverage best practices for progressive web apps including offering installation on platforms that offer it, offline awareness, etc.

C. Actual should feel comfortable on small phones. We will likely not be able to fit all components in such a small space, but Actual ought to offer a good experience down to 375 x 667 pixels (that is, 750 x 1334 with pixel device ratio 2). This is equivalent to iPhone SE.

Intended Feature Comparison

Mobile	Desktop
Transaction entry and edit done via modal/page/other	Transaction entry and edit done inline
Budget display limited to one month at a time	Flexible budget display, up to several months side-by-side depending on available space

Shared features
Transactions may be viewed per-account or all together (“All accounts”)
Uncategorized transactions

For now, it is not a community priority to bring other features to mobile. Specifically, this means we do not currently want to build mobile features to manage Settings, Payees, Rules, and Schedules, nor to view Reports.

Methods

1. Wherever practical, pages should be mobile-first responsive. For certain complex pages, we'll render different components for desktop and mobile.

   • Pro: This reduces the chance a dev focused on mobile breaks desktop and vice versa.
   • Con: This increases the chance desktop and mobile features diverge. Given the current disparity between the two platforms, this is not a big concern.
   • Complex pages today are:
     • main budget view
     • account transactions lists
     • Reports

2. Maintain a top-level React.Context to track which mode we're in, mobile or desktop

   • Any component can tap into this as needed

3. Use CSS media queries for responsiveness within a component or view, not for deciding whether we're desktop or mobile

   • Examples:
     • whether to hide a component like the floating sidebar on mobile -> decided by context
     • differing flex alignment based on available space -> media query

4. Utilize distinct routes where mobile components or interactions differ from desktop. Same route means same view.

   • Example suggestions
     • [DESKTOP & MOBILE] /accounts/<uuid>/transactions: account transaction list
     • [MOBILE] /accounts/<uuid>/transactions/new: transaction entry modal
     • [MOBILE] /accounts/<acct_uuid>/transaction/<tx_uuid>: transaction edit modal
     • …same pattern for various budget interactions requiring data entry
   • On desktop, these routes redirect sensibly.
     • For instance, transaction routes that don't exist on desktop could fall back to the account transaction list

5. Desktop components should still be responsive

   • Reasonable min-widths
   • Fill available space with wider components or more components

Areas of Work Related to Mobile Support

• Global desktop/mobile context [[🚀 Merged]]

• Basic mobile transaction entry/edit [[🚀 Merged - thanks, @Cldfire]]

  • Support for all but split transactions has been merged. Separated that feature into its own TODO item.
  • The old native app had modals for this. Quickest way to get a decent modal layout and match Actual styling is to port these to web.
  • Edit modal views could correspond to new routes as suggested above.

• Split transaction support on mobile

• Mobile budget editing

  • The native apps offered inline editing of budget cells. These cells were ported for our read-only mobile view. Editing will need to be re-enabled.
  • We won't be able to utilize the keyboard-avoiding features of RN or special buttons above the keyboard (circled below). (Not ready out-of-the-box doesn't meant we can't build the same functionality.)
    

• Desktop responsiveness

  • Many desktop views could be improved to gracefully handle being resized to narrow widths. Efforts can be focused on screen widths above our desktop minimum.

• PWA Support

  • Android PWA install
    • service worker, manifest, icon, etc.
  • Leverage what support iOS has via "Add to Home"
  • Needs to handle all platforms, so could be ideal for 2 or more devs to collaborate on this

[modrzew]

Hey there! Raising my hand for the mobile transaction entry/edit screen. As I'm using Actual now this is a feature I'm missing much from the YNAB mobile app. I'm happy to try diving into the old code and salvage what can be reused.

As for the RFC itself, it looks really solid 🚀 that being said, I'll probably have more constructive feedback once I get to play with how Actual used to look like on mobile 😄

[Sinthoras7]

Yes, I also want to say thank you for developing this software and that it is in my opinion essential to create a possibility to add transactions on mobile (and that a PWA would be great).

[edersong]

Agreed!!
If a pool is created, it will win for sure!!

[aaroneiche]

I've only begun to use Actual, so I'm still getting my feet wet. I wanted to add that a mobile interface (especially a responsive one) needs to be quite flexible to the different screen sizes out there. I raise this personally because I'm an iPhone 12 Mini user - my screen dimensions are substantially smaller than many mobile users.

[trevdor]

@aaroneiche That’s a good call-out! I‘ll add a note to the RFC when I’m back at my computer. We’ll definitely accommodate the smallest phones. I’m on an iPhone 13 mini myself.

[trevdor]

@modrzew Any luck reviving those React Native components for web?

I think I'll find time soon to help move this forward, but want to make sure I don't start a separate effort from you.

[modrzew]

Hey @trevdor, nope, sorry — I attempted to run the React Native app a few times since then, and each time I went down the rabbit hole of why it's not working on my Mac, until real life called me back 😞 that's the bad news. The good news is, because of that I'm not blocking you 🙂

[Meganitrospeed]

Is there any reason we just dont modify the current Play Store and iOS app and make them compatible with Self-Host?
Ofc it costs money to host at iOS and Play Store, there are free repositories though or we can just make it available on the github repo

[alekslyse]

First I want to say its a great project and I actually had no idea it existed before just stumbling over it today. Currently using ynab and can just speak for that.

is it more than the mobile ui of the server version? I spun this up in docker and at least me, I found the mobile version lacking in basic things like assigning categories and payees on mobile. Would it not be natural to be able to sort transactions on the phone?

I sadly don’t have time to start with helping too much, though maybe I will!

The creator should setup a sponsorship option as at least I would be more than happy to sponsor with some bucks pr month.

I also agree with those who said why not let the native apps use the self hosted?

[aaroneiche]

is it more than the mobile ui of the server version? I spun this up in docker and at least me, I found the mobile version lacking in basic things like assigning categories and payees on mobile. Would it not be natural to be able to sort transactions on the phone?

Yes - That's in fact what this particular issue is all about. Actual started out as proprietary code sold as a service. When it became an open source project the focus became getting a working version and accommodating the immediate needs of the community. There are few of us, so it's up to whomever wants to work on the code and work on what. The reason for the mobile version's limited functionality is of necessity.

I also agree with those who said why not let the native apps use the self hosted?

That's certainly an option. I think the problem at this point comes down to:

1. Bringing the Mobile code up to feature match with the actual-server deployment
2. Build process and deployment to App Stores.

With Apple (and to a lesser extent Google) there are a number of hoops to jump through to get an app to run on a device. It has to be built, signed, and distributed (the last one requiring a paid Apple Developer Account) This is why it's appealing to work on the mobile version of the server frontend - It's automatically part of the deployment, it's free, and doesn't require any additional monetary cost. Android's a little easier because you can side load, but it's still a hassle.

[aaroneiche]

I realize that templates are still an experimental feature, but thinking on it I feel like we need a proper "template constructor" tool rather than just writing something out in the category notes, as this experience is likely to be pretty awkward on a mobile screen.

[j-f1]

Agreed, see my comment on #496.

[ashutoshsaboo]

Hi all, just stumbled upon this issue. I was searching for a similar mobile support of actual budget and came across this ios app - https://apps.apple.com/in/app/actual-budget-your-finances/id1444818585 . It uses Actual Budget not just in name, but also if you expand it's overview/app description section it has links pointing to same domain name: actualbudget.com as well, which makes me wonder . Just wanted to double check is this an official app by Actual budget or a bad impersonation of actual budget by some other company?

[YagiOoda]

Hi all, just stumbled upon this issue. I was searching for a similar mobile support of actual budget and came across this ios app - https://apps.apple.com/in/app/actual-budget-your-finances/id1444818585 . It uses Actual Budget not just in name, but also if you expand it's overview/app description section it has links pointing to same domain name: actualbudget.com as well, which makes me wonder . Just wanted to double check is this an official app by Actual budget or a bad impersonation of actual budget by some other company?

This is from the previous Actual Budget before it went open source. It points to the old website which is currently transitioning to the community! That app will not be able to connect to open source instances.

[jlongster]

@ashutoshsaboo that is the official app for the hosted version of Actual. I'm the creator of Actual and it used to be a closed source subscription and I supported these native apps. The hosted subscription is being wound down however, along with these apps. I'm working on this right now.

The code for the mobile apps still exists; it used to be in this repo but because it's not supported has been moved here: https://github.com/actualbudget/actual-mobile-archive. Overall, getting it to build is complicated, but you could theoretically do it and get it working with your own version. It's complicated by the fact that Actual is a fully local app, so the entire app has to run on mobile. I did this by using nodejs-mobile which is unfortunately not being maintained anymore.

[ashutoshsaboo]

Ohh thanks @jlongster , @YagiOoda for clarifying!

@jlongster : Would it be please possible to add a "configure remote host" base url at the login time in the ios/corresponding platform apps? That ways everyone could just plug in their own base remote actualbudget host instance urls - and the same app could make those requests dynamically to the correct host? Many apps do it similarly - for example check out https://standardnotes.com they also support logging in using self hosted instances from their own original web/ios/android app itself. This is because for everyone to build their ios app clone and listing it on ios app store for updates, is a much more complicated process rather than just self hosting the backend server which the same common actualbudget app can invoke? Thoughts?

It also stays much more safer that ways.

[rich-howell]

Ohh thanks @jlongster , @YagiOoda for clarifying!

@jlongster : Would it be please possible to add a "configure remote host" base url at the login time in the ios/corresponding platform apps? That ways everyone could just plug in their own base remote actualbudget host instance urls - and the same app could make those requests dynamically to the correct host? Many apps do it similarly - for example check out https://standardnotes.com they also support logging in using self hosted instances from their own original web/ios/android app itself. This is because for everyone to build their ios app clone and listing it on ios app store for updates, is a much more complicated process rather than just self hosting the backend server which the same common actualbudget app can invoke? Thoughts?

It also stays much more safer that ways.

Hello,

Thanks for your message, the mobile apps are no longer supported by the Actual Budget OSS project, if we start making changes for one person then we will have to make changes for everyone, you are however free to clone them, edit as you wish but they will not be included in the Actual repo.

We have a responsive mobile version of the web app which is the focus for actual budget now.

The mobile apps are and will not be revived into support for Actual Budget.

Thanks
Rich

[jlongster]

@ashutoshsaboo To add more to what Rich said, distributing native apps is extremely difficult, requiring fees, configuration, certs, complicated build processes twice (for iOS and Android which have 2 completely different systems). I should have made the webapp responsive from the beginning and avoided the native apps. It would have freed up a lot of my time. There won't be any more updates to the mobile App and it'll be removed soon.

It's not as simple as just updating it once for the self-hosted version; as the webapp changes the community would have to also deploy a new mobile app each time. This is especially the case with Actual which is a fully local app, so the entire app runs on your phone. Any logic that changes for the app would have to be deployed there. Like Rich said, the community decided to invest in the webapp (which I think is a smart choice)

[ashutoshsaboo]

Thanks @jlongster @rich-howell for chiming your thoughts! I agree a responsive PWA with mobile support would indeed be far more sustainable and easy to manage in comparison to apps for various platforms.

Just one small query @rich-howell : when you mentioned above that the current focus is to make a "responsive mobile version of the web app" - i understand responsiveness, but are you also planning to make it a PWA so it can be installed on mobile homepage (as well as on desktops) to give a native feel of an app? That should give the best of both worlds too. What do you think? Is that something that could be doable?

[trevdor]

Just one small query @rich-howell : when you mentioned above that the current focus is to make a "responsive mobile version of the web app" - i understand responsiveness, but are you also planning to make it a PWA so it can be installed on mobile to give a native feel of an app? That should give the best of both worlds too. What do you think? Is that something that could be doable?

Definitely, @ashutoshsaboo! That’s where we’re headed. Installable with offline support (we’re a local-first app, after all).

I think once the mobile UI is a little further along, it will be appropriate to start adding things like a manifest, service worker, and all the stuff installable apps need. Something I’m interested in working on, among others.

[ashutoshsaboo]

That's really nice to hear, @trevdor ! 🚀🚀 Really looking forward to more updates for mobile PWA support!!

[ezra-en]

...I should have made the webapp responsive from the beginning and avoided the native apps. It would have freed up a lot of my time. There won't be any more updates to the mobile App and it'll be removed soon.

... Like Rich said, the community decided to invest in the webapp (which I think is a smart choice)

Just wondering, what's stopping us from having the native app point to the webapp? As long as the webview supports PWAs, we shouldn't have too much of a problem if we solve the storage portability issue.

Seems like there are other, slightly different alternatives as well: https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Guides/Making_PWAs_installable#installation_from_an_app_store

[rmarfil3]

...I should have made the webapp responsive from the beginning and avoided the native apps. It would have freed up a lot of my time. There won't be any more updates to the mobile App and it'll be removed soon.
... Like Rich said, the community decided to invest in the webapp (which I think is a smart choice)

Just wondering, what's stopping us from having the native app point to the webapp? As long as the webview supports PWAs, we shouldn't have too much of a problem if we solve the storage portability issue.

Seems like there are other, slightly different alternatives as well: https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Guides/Making_PWAs_installable#installation_from_an_app_store

I think the issue is more than just maintaining separate code bases for different platforms, but also the overhead of setting up pipelines, going through app reviews, dev subscriptions/payments, resolving specific platform issues, etc. for each of the popular app stores. Going with webapp, those overheads are eliminated and devs can just focus on the app.

[CharlieMK]

Hello! Very recent user of Actual here. I’m still exploring the options. But also happy to think along and provide feedback. After reading through this RFC, I understand the reason for focusing on the web app. I do have two comments:

1. What puzzles me a bit is why there does seem to be focus on developing a desktop app while for mobile there seems to be agreement to use the web version. Were there specific reasons that led to this decision? I would guess these reasons would also apply to the native app discussion (personally I’d like to use my mobile phone for day to day budgeting and use a pc more sporadically for the reporting functionalities).

2. I’m using IOS lockdown mode. The web app simply does not work currently. I have attempted to investigate why, but I was unable to find out. Going for a native app would allow users like me to whitelist the native app. I know I am an edge case, but I came to Actual mostly because of a distrust in others apps that host data on private servers using proprietary code. I think the focus on security, privacy, and local first is a major advantage. This will attract more users like me who may have lockdown enabled.

[Keboose]

Is the current state of this issue implying that transactions can be added and edited in a mobile browser? I just want to make sure before I open a redundant one, because I can't seem to interact with my instance at all on mobile.

I'm running the docker image behind a reverse proxy, version 23.8.1, and my phone is a Galaxy S20 5G running Android 13 and the latest version of FireFox for Android. I also tried Chrome, with the same results. This is what I see on my phone (using the demo account rather than my real one for privacy's sake). I can't open any expense categories or edit any transactions in the Accounts page, or add any new info anywhere. If I flip the phone horizontal, it reverts back to the desktop screen, which is fully functional as far as I can tell. My real Budget account has the same behavior as the demo:

Did I mess up somewhere during setup? Or is there something else going on?

*Edited to combine images, since they were way too big stacked up.

[Kidglove57]

@Keboose the mobile transaction entry is working really well in the latest "edge" version. If you prefer to stick with "latest" then this should go live at the beginning of September.

[Keboose]

Excellent, you're correct, I was running the latest tag: I re-deployed with edge and now I have the little plus button in my accounts. I'll stick to that tag until the features are more fleshed out and merged with latest.

Thanks!

[rougsig]

Hello, what team are thinking about 3rd party uikits. For example https://github.com/ionic-team/ionic-framework
This uikit, have Android/Ios/Mobile components, web components and more.

Or use two uikits one for mobile, another for web.

Or use only 3rd party mobile uikit, do web by own.

I think its not good idea to create mobile basic components from scratch. We can use 3rd party components.

[Jackenmen]

I don't see this mentioned explicitly so I figured I'll drop a note here - the account list and single account views do not have a button for doing the bank sync, it would be great if that were added in the future in some manner.

[shall0pass]

I don't see this mentioned explicitly so I figured I'll drop a note here - the account list and single account views do not have a button for doing the bank sync, it would be great if that were added in the future in some manner.

Did you see this PR that was just merged? #1663
Does this satisfy the request?

[Jackenmen]

Awesome, thanks! I should have checked the PR list too 😄

[Jackenmen]

Feedback: It's incredibly easy to trigger the bank sync accidentally. I think there are probably a couple of reasons for this, I can think of three in particular:

• The sync gets triggered before you let go of the touch screen (meaning you can't back away once you scroll too far, even if you're still holding it)
• It is not very visibly indicated that you're at the top of the transaction list (more on that later) meaning you may think that you can scroll up when you will instead trigger synchronization
• It actually doesn't require a lot of motion to trigger, one short but fast pull will make it go off the threshold already
  • I may be imagining the part where this is an actual problem, it's hard to judge when it gets triggered while you're still holding it and could have prevented it by going in the other direction if it didn't

Now onto other feedback:

• transaction list's scroll state resets when you go back (this is what caused me to trigger sync on accident the most); this makes it hard to backfill transactions chronologically
• The back button in the top left corner cancels the changes - this, to my knowledge, is not how most (mobile?) apps work; however, even if you think that this is how it should behave, it should at least prompt for confirmation

[yaomtc]

A bit unclear on how mobile works. So Actual is a web app, self-hosted, right? When run locally on a PC, the server would run in the background, so it's fully local... but I'm thinking the server won't be running on mobile devices, so

Actual is a different kind of app. Instead of storing all of your data on the internet by default, it stores all of your data locally. That means it works regardless of your network connection, and you always have direct access to your data.

If I'm using my phone somewhere without a network connection, how would Actual work?

To use this on-the-go I would need to have the server exposed to the Internet for remote access, right? Would have to set up port forwarding, dynamic DNS...?

[Jackenmen]

The server is pretty much used only for the budget file synchronization (and GoCardless bank sync if you use that), all the actual functionality is implemented in the client, this includes operations on the database which is local to the device you use it on. This is the same for both mobile and desktop. So how it works is that without a server running, the app can still work, just can't sync.

[yaomtc]

Ah, thanks for clearing that up! So it has to be accessed from a server at least once, right? And it stays on the mobile browser storage indefinitely? Similarly to a PWA, without the other PWA features? (For now)

[trevdor]

Closing this RFC as we're well on our way with mobile features yet this document requires a ton of reading to see what's left.

Split transaction handling and then broader PWA support can be handled without this issue open.