SnailTrail Debugger

> Simple Debug Panel for Static Sites

A lightweight debug panel for static sites built with Jekyll, Eleventy, Hugo, and other static site generators. Inspired by Laravel's debug bar, Snail Trail provides real-time performance metrics, resource analysis, and development insights—all accessible via a sleek pull-up panel.

🟫 Features

- Performance Monitoring - TTFB, FCP, LCP, Resource Timing
- Resource Analysis - Track scripts, stylesheets, images with sizes and load times
- Environment Info - Viewport, user agent, connection type, color scheme
- JavaScript State - LocalStorage, SessionStorage, cookies, event listeners
- DOM Analysis - Node count, depth, accessibility checks (missing alt tags)
- Console Interception - Capture and display console messages within the panel
- Build Information - Display build timestamps, git hashes, environment
- Keyboard Shortcut - Toggle with Ctrl+Shift+D
- Mobile Friendly - Debug on any device without DevTools
- Customizable - Drag to resize, persistent state
- logcad intergration, catches dispatched log messages from logd
- Simple usage: localstorage variable, window __BUILD_TIMESTAMP__, __BUILD_HASH__, __BUILD_ENV__
- UI memory: Remember UI state: open, close, height

🟫 Quick Start

$3

- Ctrl+Shift+D - Toggle debug panel visibility

$3

🔘 Option 1: Direct Include auto load
1. Link script file local or from cdn:
``html



// PENDING <-------
`
2. Basic Usage Vanilla JS, just set the localstorage varriable __snail_debug to true;

`javascript
// In browser console or your script set __snail_debug to true
localStorage.__snail_debug = 'true';
// if you've linked debugger.js as standard script, it will auto run initialization automatically
// can always set a button to do this
// Looks for
// - __snail_debug in LocalStorage
// - __BUILD_TIMESTAMP__, __BUILD_HASH__, __BUILD_ENV__ in window
`

🔘 Option 2: NPM | Module ( type="module" )
1. Install snail trail debugger
`bash
npm install snailtrail-debugger
`
2. Import requred functions

`javascript
import { SnailTrailDebugger, initSnailTrailDebugger } from 'snailtrail-debugger';
`

3. Modern Usage with ES6
Enable the debugger:
`javascript
// In browser console or your script set __snail_debug to true
// Initialize the debugger
const SnailTrailDebugger = new SnailTrailDebugger({
storageKey: '__snail_debug'
parnelId: 'debug-panel'
buildInfo: {
timestamp: '2024-11-14 10:30:00',
hash: 'abc123def456',
env: 'production'
}
});
// call init function to setup event listners
initSnailTrailDebugger();
`

🟫 Static Site Generator Integration

$3

`html





{% if jekyll.environment == "development" %}
{% include debug.html %}
{% endif %}
`

$3

`javascript
// .eleventy.js
eleventyConfig.addShortcode("buildInfo", function() {
return

;
});
`

`html

{% if env == "development" %}
{% buildInfo %}

{% endif %}
`

$3

`html





{{ if eq hugo.Environment "development" }}
{{ partial "debug.html" . }}
{{ end }}
`

🟫 Styling

The debugger includes minimal default styles. You can customize by targeting these classes:

`css
.debug-panel { / Main container / }
.debug-handle { / Drag handle / }
.debug-controls { / Top control bar / }
.debug-tabs { / Tab buttons / }
.debug-content { / Content area / }
.tab-content { / Individual tab panels / }
.debug-list { / List items / }
`

🟫 API Methods

`javascript
// Refresh all data
window.snailDebugger.refresh();

// Destroy and remove panel
window.snailDebugger.destroy();

// Access console log programmatically
console.log(window.snailDebugger.consoleLog);
`

Use Cases

- Local Development - Monitor performance during development
- Client Demos - Show technical metrics to stakeholders
- Mobile Testing - Debug without remote DevTools
- Performance Audits - Quick performance overview
- Accessibility Checks - Find images missing alt attributes
- Build Verification - Confirm correct build artifacts deployed

Best Practices

1. Only enable in development - Use environment checks in your templates
2. Inject build info - Makes debugging production issues easier
3. Use keyboard shortcut - Quick toggle without scrolling
4. Monitor console tab - Catch JavaScript errors early
5. Check failed resources - Identify broken asset links

Security Note

The debugger only collects client-side data that's already accessible through the browser. It does not:
- Send data to external servers
- Access sensitive cookie values
- Expose server-side information
- Store data beyond LocalStorage

However, always disable in production unless needed for specific debugging scenarios.

Troubleshooting

Panel doesn't appear:
- Check localStorage.__snail_debug is set to 'true' (string, not boolean)
- Ensure script is loaded after DOM is ready
- Check browser console for JavaScript errors

Build info shows "Not configured":
- Verify build variables are being injected
- Check window.__BUILD_TIMESTAMP__` etc. are defined before debugger initializes

Performance metrics show N/A:
- Some metrics require HTTPS (like connection type)
- LCP requires user interaction on some browsers
- Wait for full page load before checking

License

MIT License - feel free to use in personal and commercial projects.