Dom-filenameify NPM

dom-filenameify

A browserify transform that adds filenames as attributes to your DOM elements to help locate them in code via inspect element

Initial Motivation

If you've ever helped with onboarding someone onto a team you've likely gotten a flood of "How do I find BLANK?" questions.

dom-filenameify hopes to address part of this problem by annotating DOM nodes in your browser with an attribute that tells you where to find it in code.

How?

dom-filenameify alters your hyperscript style DOM builder calls and tagged template literal DOM builder calls in order to make them generate DOM notes that have a data-filename attribute with a value of the file's filepath.

It does this by walking your AST and inserting filename attributes appropriately.

To Install

You should really only use this transform in development. Especially since it's stability:experimental at this time.

To install the CLI use

npm install --save-dev dom-filenameify

To install the API use

npm install --save dom-filenameify

Examples

Here are some examples of what happens when you use this transform

// Handles nested DOM elements
var html = require('choo/html')

html`<div><span id='some-id'>hello world</span></div>`
// -> <div filename="/app/some-component.js"><span filename="/app/some-component.js" id="some-id">hello world</span></div>

var vdom = require('virtual-dom')
// Recognizes the `h` property on your `virtual-dom` variable
var h = vdom.h

h('div', {
  style: {color: 'red'}
}, 'foo')
// -> <div filename="/app/my-component.js" style="color: red;"></div>

// Variable name doesn't matter
var xyzw = require('react')

xyzw.createElement('span', 'hello')
// -> <span filename='/src/some-file.js'>hello</span>

var react = require('react')
var hx = require('hyperx')(react.createElement)

hx`<b>A bold element</b>`
// -> <b filename="/app/bold-elements/a-bold-element.js"></b>

CLI Usage

browserify index.js -t dom-filenameify > bundle.js

API Usage

var browserify = require('browserify')
var domFilenameify = require('dom-filenameify')

var b = browserify('index.js')
b.transform(domFilenameify)

// Writes output to console
b.bundle().pipe(process.stdout)

Something broke!

Sorry about that! You get a golden star if you open up a failing PR that highlights what's going wrong. You get a slightly less shiny silver star if you open up an issue describing the error. At any rate, let's get this fixed!

To Test:

$ npm run test

TODO:

Handle <img></img> issues. This breaks dom-filenameify. Should just skip over these incorrectly used

Notes

What is the hyperscript API?

The hyperscript API is domBuilder(htmlSelector, properties, children)

See hyperscript api

// hyperscript API examples
h('span', {style: {color: 'blue'}, id: 1}, 'foo bar')
react.createElement('div', [
  'a text node',
  react.createElement('span', {
  }, 'a span node'),
  'another text node'
])