A template repository for creating custom themes and shortcuts for til.re.
See QUICKSTART.md for a step-by-step guide to create your first plugin.
| Theme | Description |
|---|---|
hello |
Minimal starter theme - perfect for learning |
gradient |
Advanced theme with animations and custom parameters |
| Shortcut | Time | Description |
|---|---|---|
focus |
25m | Simple focus timer |
break |
5m | Short break with green color |
focus-loop |
25m | Pomodoro-style with rest periods |
workout |
30s | HIIT-style workout intervals |
meditation |
10m | Meditation timer |
cooking |
3m | Cooking timer with minutes display |
presentation |
15m | Presentation timer with large scale |
demo-gradient |
5m | Demo using the gradient theme |
Click "Use this template" on GitHub or clone this repository:
git clone https://github.com/til-re/plugin-template.git my-plugins
cd my-pluginsStart a local server to preview your themes:
# Using Node.js npx serve . # Or using Python python -m http.server 8080
Then open http://localhost:8080/dev-server.html in your browser.
- Theme: Copy
themes/hello/and modify - Shortcut: Add entries to
shortcuts/demo.jsonor create a new pack
Push your repository to GitHub. Your plugins will be available at:
# Theme
https://til.re/25m?theme=@your-username/your-repo:your-theme
# Shortcut
https://til.re/@your-username/your-repo:your-shortcut
Themes control the visual appearance and user interactions of the timer.
registry.json # Plugin discovery (name, description, counts)
themes/
├── index.json # Theme catalog (id, name, description, path, preview)
└── your-theme/
├── manifest.json # Theme metadata
├── preview.png # Theme preview image
├── your-theme.js # Theme renderer
└── your-theme.css # Theme styles
See docs/theme-api.md for the complete API reference.
Shortcuts are predefined timer configurations with semantic names.
shortcuts/
├── index.json # Shortcut catalog
└── your-pack.json # Shortcut definitions
See docs/shortcuts-guide.md for details.
A theme must implement these methods:
const MyTheme = { id: 'my-theme', // Must match manifest.json handlesControls: false, // Set true to handle click/keyboard defaults: {}, // Default config values init(container, config, actions) { /* Create DOM */ }, render(remainingMs, context) { /* Update display */ }, setTitle(text) { /* Update title */ }, setMessage(text) { /* Update message */ }, setState(state) { /* Handle state changes */ }, destroy() { /* Cleanup */ } }; // Export for plugin loading window.TilrePlugin_mytheme = MyTheme;
These utilities are available in the til.re environment:
| Utility | Description |
|---|---|
TimerUI.create(container, units) |
Create timer DOM structure |
TimerUI.update(elements, timeData) |
Update timer display |
TimeFormatter.decompose(ms, units, compact) |
Format time data |
Audio.play(type) |
Play sound ('tick', 'complete', 'rest') |
Audio.toggle() |
Toggle mute |
- QUICKSTART.md - Get started in 5 minutes
- docs/theme-api.md - Complete theme API reference
- docs/shortcuts-guide.md - Shortcuts development guide
- docs/faq.md - Frequently asked questions
After publishing to GitHub:
# Use the hello theme
https://til.re/5m?theme=@til-re/plugin-template:hello
# Use the gradient theme
https://til.re/5m?theme=@til-re/plugin-template:gradient
# Use the focus shortcut
https://til.re/@til-re/plugin-template:focus
# Use gradient with custom colors
https://til.re/5m?theme=@til-re/plugin-template:gradient&gradientColors=ff6b6b,4ecdc4
MIT