Server
The Server module provides the dev and prod functions. These start up a "development" and "production" server respectively.
dev features
The development server optimises for developer-experience rather than runtime performance. Some of the features require Revise.jl to function, ensure that you have that package setup in your global environment before starting the server.
Automatic Page Updates
Automatic page updates on file changes without refreshing browser tabs. This will watch all source files for changes and push the updated HTML to the browser via SSE (server sent events). New HTML content is swapped with the current HTML with idiomorph.
This feature integrates with Revise and a router auto-reloader, which allows for addition and removal of route definitions in the server without the need to restart it. The usual limitations of Revise apply to this feature, ie. no struct re-definitions, etc.
Automatic Browser Tab Opening
When starting up a dev server a browser tab is opened pointing to the / route. On macOS if using a Chromium-based browser then if there is alread a tab open pointing at this server then it is reused. This uses the same approach used by Vite.
Source Code Lookup
"DOM-to-Source" lookup, via HypertextTemplates.jl. When using this package for template rendering source information for all nodes in the rendered web page are stored and can be used to jump to the source location in your default editor by selecting a part of the webpage, typically some text, and pressing Ctrl+2. Pressing Ctrl+1 will jump to the root @render macro call that generated the element, which can be useful if the current state of a page consists of HTML generated by different routes. This feature requires Revise to be imported for it to function.
/docs/ route
All documentation for defined routes that make up the application is available at the /docs/ route. This change be changed via the docs keyword provided by dev. This provides a summary overview and details view for each route, which includes any attached docstrings, path, query, and body types, along with source code links that will open your default editor to the source of the route.
/errors/ route
Any errors that are thrown during development cause a separate browser tab to open with an interactive view of the stacktrace and error message. Source links in the stacktrace are clickable and open your default editor at that location.
The /errors/ root route itself lists all errors that the application has encountered while running, and allows you to navigate back to previous errors.
The name of this route change be changed if it conflicts with your application by changing the errors keyword in the dev call.
prod features
The prod function removes all the above features of dev. Aside from that the interface is identical. The production server optimises for runtime performance, avoid attempting to develop your application using prod since the experience will not be particular nice. Ensure that Revise is not loaded when running a server via prod in production since you may leak source location information from rendered templates.
Docstrings
ReloadableMiddleware.Server.dev — Methoddev(; router_modules, middleware, watch_file_types, docs, errors, kwargs...)Start up a development server. Code revision via Revise integration is enabled if that package is loaded. The provided router modules reflect changes to router structure on code revisions. When file types in the provided watch_file_types change then automatic browser reloading occurs, which hot-swaps the current DOM with the updated DOM for the current URL. If using the HypertextTemplates package for view templates then source code lookup is enabled via mouse hover and Ctrl+1 (for router location) and Ctrl+2 (for template location).
Returns a server Task and the file watcher object and runs the server in the background so that the REPL can be used to inspect server state.
This function automatically tries to open your web browser to the server address once it has started the server. If you are on macOS and your browser is a Chromium-based one then if a tab is already open at the correct URL then it will reload that tab, otherwise it will open a new browser tab.
The docs route provides an overview of all available routes defined within the application.
The errors route provides an overview of all thrown errors and their stacktraces. Errors can be inspected within the details view of each error. Source links will navigate your editor to the specific file and line of the stacktrace.
ReloadableMiddleware.Server.prod — Methodprod(; port = 8080, router_modules = [], middleware = [], kwargs...)Start up a production server. No code revision, auto-reload, or template lookup is enabled for this server, unlike the dev server. This function blocks until the server is closed.