Caching this blog...
`)} 105 | ${when(error, () => html`Failed to cache blog.
`)} 106 | ${when(success, () => html`Blog cached for offline reading pleasure.
`)} 107 | `} 108 | 109 | `} 110 | 111 | ` 112 | } 113 | } 114 | ``` 115 | 116 | This is cool, because it'll show pending/error/success states on the page without using any client-side JS (other than the service worker itself, of course) 117 | 118 | Anyways, lots more to build and explore with. If you're interested in seeing how this blog was set up, you can take a look at the repository [here](https://github.com/thepassle/blog). -------------------------------------------------------------------------------- /blog/practical-barrel-file-guide-for-library-authors/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Practical barrel file guide for library authors 3 | description: What to do, what not to do 4 | updated: 2024-06-01 5 | --- 6 | 7 | # Practical barrel file guide for library authors 8 | 9 | Over the past couple of months I've been working on a lot on tooling against barrel files. A barrel file is essentially just a big **index.js** file that re-exports everything else from the package. Which means that if you import only one thing from that barrel file, you end up loading everything in its module graph. This has lots of downsides, from slowing down runtime performance to slowing down bundler performance. You can find a good introduction on the topic [here](https://marvinh.dev/blog/speeding-up-javascript-ecosystem-part-7/) or a deep dive of the effects of barrel files on a popular real world library [here](/blog/barrel-files-a-case-study). 10 | 11 | In this post, I'll give some practical advice for library authors on how to deal with barrel files in your packages. 12 | 13 | ## Use automated tooling 14 | 15 | First of all, automated tooling can help a lot here. For example, if you want to check if your project has been setup in a barrel-file-free way, you can use [barrel-begone](https://www.npmjs.com/package/barrel-begone): 16 | 17 | ``` 18 | npx barrel-begone 19 | ``` 20 | 21 | `barrel-begone` will analyze **your packages entrypoints**, and analyze your code and warn for various different things: 22 | 23 | - The total amount of modules loaded by importing the entrypoint 24 | - Whether a file is a barrel or not 25 | - Whether export * is used, which leads to poor or no treeshaking 26 | - Whether import * is used, which leads to poor or no treeshaking 27 | - Whether an entrypoint leads to a barrel file somewhere down in your module graph 28 | 29 | 30 | ## Lint against barrel files 31 | 32 | Additionally, you can use linters against barrel files, like for example [eslint-plugin-barrel-files](https://www.npmjs.com/package/eslint-plugin-barrel-files) if you're using ESLint. If you're using tools like `Oxlint` or `Biome`, these rules are already built-in. This eslint plugin warns you against authoring barrel files, but also warns against importing from other barrel files, and helps you avoid using barrel files all around. 33 | 34 | ## Avoid authoring barrel files 35 | 36 | For example, if you author the following file, the eslint plugin will give a warning: 37 | 38 | ```js 39 | // The eslint rule will detect this file as being a barrel file, and warn against it 40 | // It will also provide additional warnings, for example again using namespace re-exports: 41 | export * from './foo.js'; // Error: Avoid namespace re-exports 42 | export { foo, bar, baz } from './bar.js'; 43 | export * from './baz.js'; // Error: Avoid namespace re-exports 44 | ``` 45 | 46 | ## Avoid importing from barrel files 47 | It will also warn you if you, as a library author, are importing something from a barrel file. For example, maybe your library makes use of an external library: 48 | 49 | ```js 50 | import { thing } from 'external-dep-thats-a-barrel-file'; 51 | ``` 52 | 53 | This will give the following warning: 54 | 55 | ``` 56 | The imported module is a barrel file, which leads to importing a module graph of${date.toISOString().split('T')[0]}, ${capitalize(kind === 'thoughts' ? 'thought' : 'blog')}
133 |${description}
134 |${post.description}
223 |Failed to fetch blog.
`)}\n ${when(status.success, () => data)}\n `}\n \n `\n}\n\nexport const router = new Router({\n routes: [\n {\n path: '/',\n render: ({url, params, query, request}) => { \n const overview = fetch(url.origin + '/output/overview.html');\n\n return html`\n <${Html} title=\"Passle\">\n\n Not quite blogs, not quite tweets. Something in between. Likely opinionated, potentially wrong. Subject to change over time.\n
\n ${overview}\n \n `\n }\n },\n {\n path: '/definitions',\n render: ({url, params, query, request}) => { \n\n return html`\n <${Html} title=\"Definitions\">\nFailed to fetch blog.
`)} 19 | ${when(status.success, () => data)} 20 | `} 21 | 22 | ` 23 | } 24 | 25 | export const router = new Router({ 26 | routes: [ 27 | { 28 | path: '/', 29 | render: ({url, params, query, request}) => { 30 | const overview = fetch(url.origin + '/output/overview.html'); 31 | 32 | return html` 33 | <${Html} title="Passle"> 34 |101 | Not quite blogs, not quite tweets. Something in between. Likely opinionated, potentially wrong. Subject to change over time. 102 |
103 | ${overview} 104 | 105 | ` 106 | } 107 | }, 108 | { 109 | path: '/definitions', 110 | render: ({url, params, query, request}) => { 111 | 112 | return html` 113 | <${Html} title="Definitions"> 114 |