A lightweight, comprehensive debug panel for static sites.
stylesheets, images with sizes and load times
Viewport, user agent, connection type, color scheme
LocalStorage, SessionStorage, cookies, event listeners
Ctrl+Shift+D
logd
localstorage variable, window __BUILD_TIMESTAMP__, __BUILD_HASH__, __BUILD_ENV__
open, close, height
Ctrl+Shift+D - Toggle debug panel visibility
Option 1: Direct Include auto load
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