TRL `0.2.0-next.X` Update Marathon
Greets @FVTT ▹ Developer,
I am starting a new post to discuss / troubleshoot any problems or concerns you might have in regard to updating to the beta build of TRL
0.2.0-next.2
and beyond. The 0.2.x
release series of TRL is all about hardening & streamlining the API taking a solid 2nd+ pass over everything. It represents "peak TRL" for Svelte 4.
My goal is to ship 0.2.0
on Wednesday. It's API / feature complete, but receiving any early feedback and learning about any problems you have in updating will help me create a better official release video where I can mention aspects that will help others update. If you have time before Wednesday to start your effort now is appreciated. If you are having problems let me know here or get in contact directly. I can help out with a PR if necessary.
As mentioned it's important to get on 0.2.0
as 0.3.0
will be out ASAP addressing Foundry v13
as early in the core dev release cycle as possible. There are many refinements / sub-path export changes to account for in the 0.2.0
release.
I was able to update Automatic Animations (AA) from an really old alpha build of TRL (0.0.23
!) in 3 hours. AA is a huge package. I spent another hour adding new 0.2.0
features to AA definitely improving it. See the attached video for more details on what was fixed in 0.2.0-next.2
.
I realize I didn't put out some release / update notes which will help somewhat in the process. There aren't many breaking changes, but a pertinent one for callbacks. You'll mainly have to watch out for app header buttons and any TJSDialog callbacks as now an object is passed back instead of an argument list. Here is the overview / notes:
Package sub-path Changes:
- Widely used change: localize
is located in #runtime/util/i18n
.
- All "application shell" components are located in #runtime/svelte/component/application
.
- Several more sub-paths are refined in the runtime & standard library. Use API docs to find new sub-paths. This package overview page is handy too.
Breaking Changes:
- Runtime library
- SvelteApplication
- app header
- onPress
callback now takes an object { button, event }
. To change the button icon / label on press modify button
after destructuring.
- To define Svelte components set the svelte
property to a TJSSvelteConfig
object.
- SvelteApplication.state
method name changes. If you are serializing / storing app positional state you need to update get()
to current()
.
- get()
to current()
- getSave()
to get()
- TJSDialog
- onClose
& onPress
callbacks take an object { application }
- #runtime/svelte/store/fvtt
-> gameState
removed; use globalThis.game
in templates instead.
- All document CRUD dialogs moved to standard library #standard/application/dialog/document
- Standard library:
- Various components / mostly buttons -> onClickPropagate
to clickPropagate
- TJSMenu
/ TJSContextMenu
onPress
callbacks take an object { event, focusSource, item }
---
Refinements:
- TJSDocument
/ TJSDocumentCollection
- Improved Foundry callback registration. No need to manually call destroy()
.
- TJSGameSettings
- No longer checks for equality on game setting store update allowing objects to be stored.
------
These are many other refinements, but some of those above were concerns from various developers. Of course the breaking changes to look out for as well.
Here is the 0.2.0-next.2
/ AA update video:
https://www.youtube.com/watch?v=tlaBOCmGBe8TyphonJS
YouTube
TRL 0.2.0-next.2 Update Marathon
#1
Just a brief discussion of
0.2.0-next.2
and confirmation that Automatic Animations (AA) is now current. AA was on TRL 0.0.23
/ alpha version of TRL, so besides being a huge package it took me 3 hours to update to 0.2.0-next.1
then an extra hour to add new features from the latest TRL for modal file pickers which is a nice improvement.
I a...24 Replies
Also a heads up when using the latest Vite
5.4.10
. If you are deploying your repo directly into Data/modules/<MODULE_NAME>
using the provided Vite configs from essential-svelte-esm
or the template repo that compile to ./index.js
in the module path you will see the (!) build.outDir
warning. This is to be expected and is OK in this case.
svelte-preprocess
uses an older JS API for sass
. I'm sure this will be updated soon. You can install the latest svelte-preprocess
for Svelte 4 & 5. This is what the sass
warning refers to, but is fine. The latest is automatically installed as a peer dependency of #runtime
.Upgraded, no real issues here.
Had to upgrade
svelte-preprocess
to v6 and change a couple of imports but works fine.
I do have a minor issue with typescript not reconginzing the imports for some reason, I added them to the tsconfig as paths but still no dice, it is very minor tho and the code does compile, just an issue in webstorm it seemsRight on.. For folks that haven't dug in too deep or that are already on
0.1.x
the upgrade shouldn't be too bad. Mostly just changing sub-path exports to more refined paths. The callback changes to an object and not argument list for app header buttons / TJSDialog are a point to watch out for if used.
For instance the Automatic Animations PR was deep, but it also was coded at a much earlier point in time and uses more of TRL, so many of the points above in the list of things to watch out for were applied. AA also had problems being a large Handlebars package before conversion to Svelte. It works, but isn't a good example of how to go about things per se; no fault of the original author though. IE a very good MVP that in a professional context would get an architecture overhaul / restructure.
Regarding types for anything that touches Foundry like #runtime/svelte/application
types are withheld / not hooked up because there are no minimal types for Foundry core API / IE Application
and whatever else is referenced that are suitable to hook up. If things were quiet on the Foundry front without a looming need to address v13
immediately I was planning on making a minimal set of Foundry types for just the aspects where TRL touches Foundry, but alas things are not quiet and v13
/ 0.3.0
work to adjust to Foundry platform CSS / style changes must commence immediately to get ahead of those changes and give folks using TRL enough time to test packages on v13
. Alas I can't tie TRL to the Foundry community types for several reasons despite the effort expended by folks in that area.
I will get a types solution in place for those sub-path exports soonish, but alas not likely before v13
concerns are solved and this is mostly due to "unknowns" in Foundry platform changes at this time. As things go first / early Foundry prototype release can also be incomplete / far from finished. The big problem there is that there is no visibility when v13
will be released, so the cautious approach is to drop everything and work on that ASAP.
---
What I am working on the next two days is adding as much detail / additional API docs to in the source JSDoc / various sub-path package descriptions. I'm also going to try and get basic architecture overview / programmers guide / getting started resources together and clean up various repo guides / info.
Oh hey.... Just noticed some funky bits in the image; IE:
TRL 0.2.0
is more capable than core AppV1/V2. You can use percentages for width / height data ala
Also TRL supports setting minWidth
/ maxWidth
as data values. There are many other handy positional features.
I also highly recommend never using JQuery at this point and learning the DOM API. IE window.offsetHeight
is the same value.
Granted this thread is to support folks upgrading to 0.2.0
, but worth mentioning the above.Cool, I remmber trying that a while back and it didnt work so I went with this, I'l give it a try
The percentage support is new. The underlying TJSPosition which is what you are working with as
SvelteApplication.position
vs a bare object in the core API is quite robust / fully reactive positional store + animation / movement validation. I recommend folks check out the App Control / Animation
demo in essential-svelte-esm
.
You can do all sorts of fancy things now like relaitive adjustments: app.position.width = '+=100px'
to add 100px to current width or app.position.width = '150%~'
to make the width 150% of the current width.
Just bumped @typhonjs-fvtt/runtime
to 0.2.0-next.3
. No changes / fixes to API. I just moved all dependencies
to peerDependencies
with open forward versioning.
This benefits anyone using pnpm though you will need to use pnpm install --legacy-peer-deps
.
TRL takes advantage of the flat node_modules
structure created by NPM to install dependencies like Vite, Svelte, and everything else required as peer dependencies without requiring explicit configuration in a local project package.json
. You can now however provide explicit package dependency if desired.
----
I'll be available on Sunday to help out with any potential PRs for folks running into trouble updating to 0.2.0
. Unless any problems arise after this weekend I'll be making the final release on Monday. Just to be prudent I figured I'd give just a little more time for anyone to start the update process and report any issues. If you have the time to update this weekend please give it a shot. This is an opportunity to provide any feedback before 0.2.0
ships. It's rock solid now and there are no expected changes before final release.Alright @FVTT ▹ Developer ...
The release candidate of TRL
0.2.0
is out and available. There are no further changes expected before 0.2.0
officially goes out the door. This will occur this Friday, but glad to receive any comments before then. I will discuss some of the final refactoring and detailed testing that occurred over the last month.
For reference in package.json
this is:
I should note that TRL provides additional resources beyond the base Svelte library for advanced app development. The tools that I use to make the TRL components rock solid are available for you to use as well to make your components resilient.
In the video below I go over some of the high level architecture details and behind the scene work that I accomplished with 0.2.0
. The goal of 0.2.0
was to harden TRL from bottom to top including all dev tooling used along with API docs. All of this successful... It just took time to get it all done. TRL is well positioned now for the Svelte 5 transition.
It's a great idea to install the essential-svelte-esm demo repo:
Or the direct package link you can drop in the Foundry package manager:
- https://github.com/typhonjs-fvtt-demo/essential-svelte-esm/releases/latest/download/module.json
I will be making an official 0.2.0
release video stepping through a lot of those demos.
I can say that TRL is 100% bug / issue free. I did detailed testing and there is 1:1 complete identical behavior between Chrome and Firefox including usage of all TRL components in cross-window contexts; IE popping out an app via the PopOut!
module. This was no small feat as Firefox is quite demanding in this regard. The high level details are that the entire JS / DOM APIs are completely separate in Firefox for cross-window use cases. TRL does a lot of accessibility / focus management that involves the DOM API. The two key utility classes available are A11yHelper and the new CrossWindow.
While TRL is 100% cross-browser / cross-window certified that doesn't mean the custom components you write or any 3rd party Svelte component libraries you may use will work in a cross-window context. One must be intentional in designing for this use case.
I also tested a game controller / Rumblepad 2 w/ JoyToKey
and there are no problems using TRL w/ game controllers.
With all of the final work I did a bit of preparatory refactoring at the architecture level and some small minor adjustments to the standard library. Likely these changes won't affect you, but here they are:
- all standard components use enabled
as optional state to enable / disable.
- ripple
/ rippleFocus
were moved to the base sub-path export #standard/action/animate/composable
.
Notes about Vite 6.... Well TRL isn't the limiting factor here, but the Svelte 4 plugin for Vite is hard locked to Vite 5. The latest usable version for Svelte 4 is @sveltejs/vite-plugin-svelte
at 3.1.2
.
Also I made some adjustments to the Vite config in essential-svelte-esm
as @rollup/plugin-node-resolve
is no longer necessary for Vite 5. You will see a warning about the Sass 2 API, but that is a Vite 5 quirk changed in Vite 6. All is fine.
This was a very long year of lots of grind from bottom to top and it has been a complete success and positions TRL in a position of strength to successfully transition to Svelte 5 as well as deal with the upcoming Foundry v13 style / CSS changes. While the Svelte 5 transition will again be a slowish period once it's complete the sky is the limit
https://www.youtube.com/watch?v=CY9aedjx7X8TyphonJS
YouTube
TRL
0.2.0
Update Marathon #2 Release CandidateHey folks.. Just an impromptu video showing off the last month of extreme hardening of TRL and the standard component library including a high level architecture overview. I can now say that TRL is 100% rock solid across Chrome & Firefox not only in the main browser window, but also cross window when using the
PopOut!
module. It took a bunch o...Looking forward to Svelte 5 to start some development with TRL. I migrated all my corporate tools and websites to Svelte 5 last month and it was painful, rewriting 50% of the code to runes with barebones documentation and basically no examples / real world projects. But now that I understand Svelte 5 much better, it feels amazing to use, and I just can't downgrade to Svelte 4 for Foundry dev.
it was painfulI'm indeed concerned about this regarding folks currently using TRL / Svelte 4 on Foundry. I don't think folks realize how large / actual paradigm shift that it will be. The API surface of TRL will change certainly at the component level and folks that have serious / supported Foundry packages using TRL will have a lot of work to do despite whatever I can do on the TRL side to make things easier. There already is some pretty clear attrition between folks either leaving Foundry dev or just not interested in TRL anymore or simply stopped by temporarily to check things out, but never got started. Getting pinned between the AppV2 Foundry side and Svelte 5 is a "double whammy" so to speak. Svelte 5 still comes across as
beta
to me with non-stop fixes coming in daily and the whole WAAPI transition system has something like 60 issues that simply aren't being worked on yet. Getting through this transition I'm sure Svelte 6 will be grand.. ;P Additionally, with stock AppV2 just not being suitable for reactive frameworks despite claims, but communicating that is practically impossible on the main forums and hopefully there isn't too much confusion in discussion here.
Svelte 5 will give tremendous capabilities at the TRL / framework level though; just lots of busy work until it comes to be.
TRL will emerge through all of this strong in time. I truly believe that once reactive property field access is realized with TJSDocument
that this opens up the real power of reactivity on Foundry and it will change everything especially for game system devs.Svelte 5 still comes across as beta to me with non-stop fixes coming in dailyThat's absolutely true, they have the whole Advent of Svelte going on right now with new features announced daily https://svelte.dev/blog/advent-of-svelte There are some things that I really want to see, in particular: 1) async version of
$effect
i.e $asyncEffect
. Using async functions in effects this way is not correct because an async function returns a promise that Svelte doesn’t expect and can’t resolve:
So you need to either make it thenable
Or use immeadiate function like this:
2) Partial track on $effect
, so it will only trigger on changes I want to track, not every single variable in the function. Currently, it can be achieved with runed/watch
3) Reactive context
without classes, getters and setters. Not a big deal but it just counter-intuitive that $state
doesn't work in context without boilerplate code.I've always been somewhat amazed and personally bummed (because I'm "old school" and announce after engineering is complete) at the new school announcement and hype cycle stoked by Rich Harris and co. The pendulum is finally swinging back around where "announce early / over promise" is thoroughly hitting them in the rear.. ;P
The whole announce early to grab tech cred / headlines has a whole lot more to do with marketing than it does engineering.
Re:
#3
: While there is a lot of power with $state
when it comes to actually passing state between sources one now has to mindful of pattern construction issues. There is a lot of flexibility, but when it comes to creating a generic data source that can be shared and hooked up with generic components accepting data sources this likely requires following a very specific pattern vs a standard contract (stores). It moves the burden heavily towards sticking with a specific pattern of data construction that can be utilized by generic components that also follow that pattern. At least this is something I'll be paying attention to on the difference between stores and $state
.I mean it's trivial to make it work, I just think it's something Svelte compiler should do automatically without boilerplate.
Indeed. Svelte 6 FTW. I think we'll see a long continued dev cycle for the nearly the entire Svelte 5 timeframe. It'll be fantastic eventually.
I guess what I was hinting at not specifically the use case you mentioned is that passing stateful classes like Foo is not clear cut. I have yet to explore deeper, but I don't think you'll be able to pass
foo.value
or other properties IE foo.bar
as a generic stateful props. I'm going to be looking into creating reactive data classes for all of the TRL components... It's just not clear right now if you have a generic data source like foo.bar
that you can assign it to the data source
field of the TRL component data class. IE with stores there is a defined API contract on receiving / setting the data.
Well.. We are getting off into Svelte 5 / random chat... Definitely want to leave this thread / forum post for any feedback on the TRL 0.2.0
release.
Lots to ponder in the near future re: Svelte 5! Also glad that you are diving into Svelte 5 separately. I'm sure it'll be nice to have folks with some experience around when it comes to honing the TRL Svelte 5 experience!I will say though, working on Svelte 5 from scratch on new websites it makes previous versions syntax almost unreadable now.
I have to keep reminding myself that
let
makes things reactive just bcuzI know I mentioned not using this forum post regarding forlorn remembrances of magic past. Really that was just so folks see the above RC / video announcement, but likely those still interested have done so. One thing I'll miss a bunch is the on:pointerdown
|preventDefault|capture
event modifiers.
While there is some benefit of passing around props for event handlers IE onpointerdown
, magic and code brevity is lost. I also have a ton of custom events in TRL that are like close:popup
which I assume need to be changed as on:close:popup
will no longer be valid as onclose:popup
.
Using
<script lang="ts">
no longer works with this version?
Error: "ApplicationShell is not defined"I would suggest doing a clean install of Node packages. One way is just deleting
node_modules
& package-lock.json
. I made a lot of things peer dependencies of the runtime package. If you are using NPM then things should work.
svelte-preprocess
also lists typescript as an optional dependency, so I'd add typescript
to devDependencies
.
I won't be able to test things until Sunday. Where is that error coming from? Does it occur without lang="ts"
?
This likely is a configuration issue and nothing with TRL per se.
If you are taking the straight template-svelte-esm
to enable typescript
might be as simple as adding it as a package to install; that template covers ESM, etc.I checked out
template-svelte-esm
added <script lang="ts"
the the BaseAppShell and "typescript": "^5.4.5",
to devDependencies. Then I run npm install
and started vite devTry using the package instead of #runtime
I assume you have a recent Node version installed.
v18
+ You should see a warning otherwise.
Perhaps run npm run build
to build the normal artifacts first then npm run dev
. Also try the build and not the dev server straight out. Restart your Foundry server after the initial build. You can also check the modules section on the admin side to make sure Foundry sees it.
Where are you seeing the error? In the browser console or during the build process? I assume the latter, but perhaps you can include the output where the error is occurring.This has nothing to do at all with TRL / building / or running the module. The build should have produced information detailing aspects of TS hookup required. Maybe you didn't see this when running
npm run dev
, but it is present in npm run build
.
verbatimModuleSyntax
is required to be true in any associated tsconfig.json
which you should also add. This is a requirement of Svelte / svelte-preprocess
.
So not a TRL problem per se. It is true that I haven't been able to thoroughly go through all of the Svelte components to explicitly type props and such; several will be typed as any
, but the declarations are there. The time investment to thoroughly type all of the Svelte components is a bit moot given how much Svelte 5 is going to change things. I'd rather do a thorough job once instead of twice.
Unless you are a TS expert too you should be forewarned that using Typescript w/ Foundry in general is a really mixed bag and you should be ready for headaches.Thanks. That works for me. I already tried
verbatimModuleSyntax
before but instead of a build I just started the dev server.
Unless you are a TS expert too you should be forewarned that using Typescript w/ Foundry in general is a really mixed bag and you should be ready for headaches.Coming from a backend developer background for large enterprise applications where clean code is everything it feels just wrong not to have types 😅
There will be a few things to tidy up and improve in TRL An awful lot of time has been expended in this area otherwise the API docs wouldn't be in the state that they are presently.
The Foundry side will remain problematic.
I actually write all the types I need myself. But we are getting off topic. I really appreciate the help. I'll now try to convert my actual module to the new version.
If anything comes up / needs clarification feel free to reach out.