mirror of
https://github.com/BookStackApp/BookStack.git
synced 2026-02-05 00:29:48 +03:00
Make BookStack into a SPA #216
Reference in New Issue
Block a user
Delete Branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Originally created by @ssddanbrown on GitHub (Dec 4, 2016).
Proposal
Initial idea of converting BookStack into a JavaScript-driven single page application, Just spit-balling for now. From an initial evaluation of recent JS frameworks I think VueJS will fit well. Would want a fully component-driven interface with hot-reloading to ease development. Personally need to investigate Vuex further to see how it could be used to make state-handling sane.
Advantages
Disadvantages
Possible pain points
@Shackelford-Arden commented on GitHub (Jan 12, 2017):
I'm not heavy in development (yet) but I like the idea of a SPA. I find SPAs much more... satisfying(?) to use. I think for those who are in an environment that puts a heavy traffic load on the application might find it beneficial to have a separation of server and UI, but I don't know the finer details of if this means what I think it means (better performance?...).
From your perspective, would it be helpful to get BookStack to a stable release before doing this or would the stable release come after implementing VueJS?
@ssddanbrown commented on GitHub (Jan 14, 2017):
@Shackelford-Arden Thanks for your input. The performance of the application as a SPA will really depend on how good the implementation is. It should at least make things feel more 'reactive' like a normal desktop/mobile app (Things like not having full page refreshes when jumping between pages will be a lot nicer) so hopefully it will at least give the impression of better performance.
I've recently converted another of my sites, https://iwanttolearn.io/, into a Vue.JS based SPA and I really like the feel of it but that site is a lot simpler and is not running on a dynamic back-end which also helps greatly.
I'd probably seen this as almost a v2 release of BookStack, After a stable release, unless some features come along where it would be crucial to have this.
@thestepafter commented on GitHub (Jan 23, 2017):
You have done a fantastic job with this project so far. I really appreciate all of your hard work and the professional level of the product. I really like how fast the pages load and the user interface is extremely easy to use.
My concern with going to a SPA is that it will introduce another level of complexity that I personally don't think is needed. There is something to be said for simple applications that just work. Unless there is a compelling reason to move to a SPA I would keep BookStack as it is and focus on getting to a v1 release. I would recommend VueJS if you do decide to go SPA but my experience with SPAs has been mediocre at best and I really miss web applications that aren't SPA.
Thanks again for your time and all of your hard work.
@xorander00 commented on GitHub (Jan 23, 2017):
I'd be willing to help with this, but it would be slow as my schedule is pretty packed. I do like your project though. For an application like this, an SPA would certainly help usability.
Any particular reason for Vue.js over React? I've heard some good things about Vue.js, but haven't had the chance to look into it yet. I mainly use React. I'd be willing to whip something up to get started.
As for permissions, I haven't written any non-trivial PHP in a long time. OAuth2 tokens are kind of standard for handling authentication and authorization.
@monitaurus commented on GitHub (Jan 25, 2017):
I've got two points of view.
On one side, I think that Bookstack doesn't need SPA, it's fast enough and not complex to use.
I will have no doubt about using SPA for a highly interactive application where there is a need of smooth transition between actions.
As Bookstack interactions are, for now, mostly viewing and editing text, the interaction is therefore limited.
I think that the structure of Bookstack now (books, chapters, pages, display of one page at a time) make it more likely to use for long text rather than small text. Therefore, the time spent on viewing a page will be more important than the navigation between the pages, and navigation might not be a great pain.
On the other side, SPA may bring new possibilities or making it easier to develop new functionalities (may be a quick in text editing).
So I think that if a SPA migration is done, you may need to think about new functionalities that are too complex to be done without it first rather than the speed gain.
Finally, in both case I'm sure that BookStack will be great ;)
@xorander00 commented on GitHub (Jan 25, 2017):
I agree with what you're saying. I'm 50/50. It's pretty good the way that it is right now, but I an SPA client would help UX for certain usage patterns. For instance, I tend to edit a lot of smaller pages frequently rather than single large pages.
Either way is fine though. I don't really have any complaints as it is right now. The main things that would improve my current usage of it would be an easier way to set permissions for external users, being able to export entire books or chapters to PDF instead of just individual pages. I think I remember seeing the latter as being a feature request though, so it's probably in the works.
@xorander00 commented on GitHub (Jan 25, 2017):
Oh, and attaching files/links to an individual page instead of a whole book/chapter.
@mry commented on GitHub (Jun 10, 2017):
You can do both if you replace SPA with HTML5 like components, which can be implemented in whatever favourite js framework.
I see few reasons to switch to an SPA architecture from a user perspective.
@ssddanbrown commented on GitHub (Dec 31, 2017):
Thought about it for a year and read the points above. Decided against it for now. View system will work well for custom theme support and an extra layer of complexity is not needed right now.
@alexpotter commented on GitHub (Feb 28, 2019):
Was reading this yesterday and have a few suggestions
@ssddanbrown commented on GitHub (Feb 28, 2019):
Hey @alexpotter 👋,
Good to hear from you, and thanks for the suggestions.
An API is on the roadmap but will be an addition rather than for direct use by the BookStack view system. We generally keep the blade views to minimal logic to reduce php+html unpleasantness. As said in my last comment, the blade view system will work great for customization. We currently have the ability for users to override views on a per-file basis which allows easy customization with a low barrier to entry.
Right now we can, and do, test page content for certain actions and content which is quite nice. Doing the same for a JS-driven interface, while possible, is more complex. That's what I was referencing in regards to testing.
Agreed, I generally try to ensure any new back-end endpoints or features are tested when implemented so many of the tests could already exist.
Agreed again, If the JS codebase was going to explode in size I'd probably look to use typescript to keep things sane. Personally I'd probably go with Vue as the main library since that's what I'm familiar & efficient with.
Yeah, We're currently doing something similar, sending down translations via endpoint on load, for some front-end bits so wouldn't be tricky to support something like that fully, just have to consider scaling as there's a growing amount of text but you could look to set caching headers to help i suppose.
BookStack implements a custom permission system since it requires more advanced logic than the default laravel system provides since permissions are fine-grained and implemented on listing views. The pain point is more about "How do we adapt the current system to work over the API?". It's possible but just a fair bit more complex than the current back-end driven system.
Yeah, Again just one of those things which is doable but with additional complexity, or at least different thinking, as you abstract the back-end away from the front-end.
Yeah, Always a good idea. I've recently played with having an
apiservice in an SPA which standardises fetching, loading state & response handling which has so far worked quite well.Overall, My decision to stick with server-side-views/blade is just down to an SPA being of little benefit while making customization harder, which is fairly important to BookStack users. The forcing of an API for an SPA would have been nice but an API is planned anyway and the API separation will allow internal BookStack work to make larger changes without breaking API compatibility.
I've always liked how GitHub works, With server-side driven views enhanced with JS & turbo-links style page navigations. Is a nice in-between. I guess that's what I'm kind of striving for on this project.
@alexpotter commented on GitHub (Mar 1, 2019):
That all makes sense 😁
Views - a side note, another bonus with a SPA is if an api request fails, the page won't break, only the component that requires that response will.
Testing - laravel dusk can test an SPA as it literally opens a browser and runs the tests. It uses the same syntax as the pre dusk tests, so not too many changes there in theory.
Type checking - typescript is amazing, ensure to use a linter that will moan at you for not type hinting everything
SPA generally seems to be the way big web applications are going, the most painful bit is transpiling the code, but if you implement something like circleci, you can have that run all tests etc too. Then you can do cool things like disallow merging to master unless the checks pass. Using SPA or not, that is something that may really help you with your development if you start to test multiple areas of the system
Good work on the app though @ssddanbrown looks impressive 👨💻
@MarcusTheSmith commented on GitHub (Nov 5, 2019):
I support the SPA and a re-write to VueJS! Besides that recent additions to the Vue ecosystem would make implementation of this easier, I think that it makes it a lot more future proof and contribution friendly. Besides that, with modern Paradigms like PWAs and statically served sites built off of JS frameworks (look into Nuxt.JS) I think a v2.0 could really move Bookstack forward in user adoption. I also think that having the API built out makes it a great competitor to other Headless CMS options.
I personally would be interested in contributing to a re-adaption like this and know others who would also be interested. I was literally thinking to myself today "If Bookstack were written in Vue and had an API it would be exactly what I need".
Obviously you have done a lot of thinking about the trade-offs, but know that there is definitely support for a Vue version of BookStack if you ever decide to go there.
@ssddanbrown commented on GitHub (Nov 16, 2019):
Thanks for the offer of contribution @MarcusTheSmith but I'm very much decided against the SPA route at this time. A lot of the customisation features currently implemented/being worked on are made easy, with a low barrier to entry, via being server-side driven. Users adopting the platform for purely being an SPA would likely be a different audience to that whom we're building for.
An API is upcoming on the road-map though, regardless of SPA adoption.