FAQ and Support

Answers to the questions that come up most while building with Koyo.

How do I install Koyo?#

pip install koyoapp. The package is published on PyPI. To develop on the framework itself, clone the repository and run pip install -e . inside it. See Getting Started, Installation.

The port is already in use, how do I change it?#

You do not need to. koyoapp dev starts on port 2309 by default, or the PORT setting in koyo.config.py, or what you pass with --port, whichever is applied first. If that port is already taken, the dev server automatically moves to the next free port (2309 becomes 2310, and so on) and prints Port 2309 is already in use, using 2310 instead. You can still force a specific port with koyoapp dev --port 8000.

Where does my custom CSS go?#

Put it in styles/globals.css. Koyo compiles that file to styles/koyo.css and the root layout links it. Third-party stylesheets can sit in public/ or be served from the styles folder untouched.

Do fragments really avoid a page reload?#

Yes. An htmx request carries the HX-Request header, which Koyo detects to return only the fragment from a route that exports fragment(). htmx swaps the returned HTML into the current page without reloading it. See Interactivity.

How do I open my app from my phone?#

The dev server binds all interfaces and prints a Network URL such as http://192.168.1.42:2309. Open that on the phone while both are on the same Wi-Fi network. If it does not appear, check the macOS firewall and restrict binding with --host if needed.

Why does the build skip my blog post routes?#

Routes like app/blog/[slug]/page.py are dynamic: the build has no list of concrete slugs to prerender, so it skips them and prints a message. The listing page at /blog is still built. Static hosts cannot serve dynamic content by themselves; run a small server if you need to serve generated posts.

My counter reset. Why?#

Session state lives in server memory and resets when the server restarts, and each session expires after 30 minutes of inactivity. That is the design: Koyo's state is per-session and in memory. See State limitations before relying on it.

Do two browser tabs share state?#

Tabs in the same browser share the same session cookie, so yes, they see the same use_state values for the same keys. Two different browsers, or private windows, are separate sessions.

Where do I report a problem?#

Open an issue on the Koyo repository. Include the version, the command you ran, and the tail of .koyo/dev-server.log when the problem involves the dev server or the build.

Can I use Koyo for anything, and contribute?#

Yes. Koyo is free and open source under the MIT license. Use it anywhere, for any project, personal or commercial, for free. The license and copyright line live in the LICENSE file in the repository. Contributions are welcome: open an issue for a bug or feature, or a pull request with a change and a short description.