{"id":15314248,"url":"https://github.com/barelyhuman/preact-island-plugins","last_synced_at":"2025-04-15T01:07:31.787Z","repository":{"id":101913363,"uuid":"604418559","full_name":"barelyhuman/preact-island-plugins","owner":"barelyhuman","description":"Collection of low level plugins for different bundlers to generate and handle preact islands","archived":false,"fork":false,"pushed_at":"2024-07-01T04:21:48.000Z","size":931,"stargazers_count":16,"open_issues_count":4,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-28T13:04:11.261Z","etag":null,"topics":["esbuild","island-architecture","islands","preact","ssr"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/barelyhuman.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-02-21T02:37:56.000Z","updated_at":"2025-01-21T03:04:15.000Z","dependencies_parsed_at":null,"dependency_job_id":"7e485861-fa06-4ba2-872e-1f86e16e83ec","html_url":"https://github.com/barelyhuman/preact-island-plugins","commit_stats":null,"previous_names":[],"tags_count":42,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/barelyhuman%2Fpreact-island-plugins","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/barelyhuman%2Fpreact-island-plugins/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/barelyhuman%2Fpreact-island-plugins/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/barelyhuman%2Fpreact-island-plugins/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/barelyhuman","download_url":"https://codeload.github.com/barelyhuman/preact-island-plugins/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248981256,"owners_count":21193143,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["esbuild","island-architecture","islands","preact","ssr"],"created_at":"2024-10-01T08:44:51.248Z","updated_at":"2025-04-15T01:07:31.771Z","avatar_url":"https://github.com/barelyhuman.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# preact-island-plugins\n\n\u003cblockquote style=\"display:flex; align-items:center\"\u003e\n\u003cimg height=20 src=\"https://preactjs.com/favicon.ico\" /\u003e Preact server rendered, partial hydration and islands for everyone!\n\u003c/blockquote\u003e\n\n\u003e [!TIP]\n\u003e If you need a more flexible and functional API for building Preact islands, check out [Preland](https://github.com/dumbjs/preland)\n\n## TOC\n\n- [Highlights](#highlights)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Concepts](#concepts)\n  - [File Name Extensiom](#file-name-extensiom)\n  - [Top Level comments](#top-level-comments)\n  - [Lazy Hydration](#lazy-hydration)\n- [Limitations](#limitations)\n- [Example Configs](#example-configurations)\n- [How](#how)\n- [FAQs](#faqs)\n- [Contributing](#contributing)\n\n## Highlights\n\n- Tiny\n- Tree Shakeable\n- Flexibile / Not dependent on folder structure\n  - Use either `.island.js` file extensions for initialize islands\n  - or `//@island` top level file comments\n  - Automatic detection of an island (`since v0.1.2`)\n- Lazy Hydration Modifiers - `//@island lazy`\n\n## Installation\n\nThe installation differs based on which plugin you wish to use.\n\n### esbuild\n\n```sh\nnpm i esbuild @barelyhuman/preact-island-plugins preact\n```\n\n### rollup\n\n```sh\nnpm i rollup preact @barelyhuman/preact-island-plugins @rollup/plugin-babel @rollup/plugin-node-resolve\n```\n\nif using `typescript`, you should also add that when using `rollup`\n\n```sh\nnpm i @rollup/plugin-typescript\n```\n\n## Usage\n\n```js\n// Single Import\nconst preactIslands = require('@barelyhuman/preact-island-plugins')\n\npreactIslands.rollup(options)\n// or\npreactIslands.esbuild(options)\n\n// Tree Shakeable Import\n\n// For rollup\nconst preactIslands = require('@barelyhuman/preact-island-plugins/rollup')\n\n// for esbuild\nconst preactIslands = require('@barelyhuman/preact-island-plugins/esbuild')\n```\n\nBoth bundlers use the same Options type, please read through the API options\nbelow to configure the behaviour of the island generation\n\n```ts\nexport interface Options {\n  // The working directory of the project, Defaults to '.'\n  rootDir: string\n  // If using `atomic` components, use the baseURL to specific the path where the JS Assets will be available\n  baseURL: string\n  // when true, each island has it's own script for lazy loading JS and Interactivity\n  atomic?: boolean\n  // If working with bundlers where hashing isn't available, you can set the `hash` to true to get browsers\n  //  to load the correct JS after loads\n  hash?: boolean\n  // The plugins use your bundler (rollup, esbuild, etc) to also bundle the client asset with it's own imports\n  // so the `client` options define the behavior for that\n  client: {\n    // path of where to output the bundled components\n    output: string\n  }\n}\n```\n\n#### Concepts\n\nThe overall idea is to be able to define islands without thinking about it.\n\nThe plugins provide 2 ways to do this.\n\n##### File name extensiom\n\nYou name the file `.island.js` or `.island.tsx` and this will generate the\nisland files for you according to your build configs. Make sure you go through\nthe [playground](/playground) to better understand this.\n\n##### Top Level comments\n\nThe other options is to prefix the code with `//@island` and this is to be done\nwhere you start the file without knowing if it's going to be an islad or not.\n\nThis might look, something like this\n\n```js\n//@island\n\nexport default function Counter() {\n  const [count, setCount] = useState(0)\n  return \u003c\u003e{count}\u003c/\u003e\n}\n```\n\n##### Lazy Hydration\n\nThe islands generated by this plugin is already lazy loaded, so you don't have\nto ever set it up and the browser will take care of handling the cache of the\nfile. Though, we do provide with lazy hydration which can help with performance\nwhere the JS is downloaded earlier but is not applied to the DOM element unless\nit's in view.\n\nIt would look something like this\n\n```js\n//@island lazy\n\nexport default function Counter() {\n  const [count, setCount] = useState(0)\n  return \u003c\u003e{count}\u003c/\u003e\n}\n```\n\nYou can also define the threshold of visibility by adding a number from `0` to\n`1` to the `lazy` modifier.\n\n- `0` - Hydrate as soon as the element is in view.\n- `0.5`(default) - Hydrate after at least 50% of the element is in view\n- `1` - Hydrate after the whole element is in view\n\n```js\n//@island lazy:0.2\n//              ^ hydrate Counter after 20% of the element is in the viewport\n\nexport default function Counter() {\n  const [count, setCount] = useState(0)\n  return \u003c\u003e{count}\u003c/\u003e\n}\n```\n\n### Limitations\n\n- Only allows Single default export to be an island\n  [right now](https://github.com/barelyhuman/preact-island-plugins/issues/10)\n- Bug with Text based containers\n  [#4](https://github.com/barelyhuman/preact-island-plugins/issues/4)\n\n## Example Configurations\n\n```js\n// build.js\n// for esbuild\nconst esbuild = require('esbuild')\nconst preactIslands = require('@barelyhuman/preact-island-plugins/esbuild')\n\nesbuild\n  .build({\n    entryPoints: ['./server.js'],\n    format: 'cjs',\n    target: 'node16',\n    platform: 'node',\n    bundle: true,\n    jsx: 'automatic',\n    jsxImportSource: 'preact',\n    loader: {\n      '.js': 'jsx',\n    },\n    outdir: 'dist',\n    plugins: [preactIslands()],\n  })\n  .then(_ =\u003e process.exit(0))\n  .catch(_ =\u003e process.exit(1))\n```\n\nFor rollup, it might look something like this\n\n```js\n// rollup.config.js\nconst { nodeResolve } = require('@rollup/plugin-node-resolve')\nconst { babel } = require('@rollup/plugin-babel')\nconst preactIslands = require('@barelyhuman/preact-island-plugins/rollup')\nconst { DEFAULT_EXTENSIONS } = require('@babel/core')\nconst typescript = require('@rollup/plugin-typescript').default\n\n/**\n * @type {import(\"rollup\").RollupOptions}\n */\nmodule.exports = {\n  input: 'server.js',\n  output: {\n    dir: 'dist',\n    format: 'cjs',\n  },\n  plugins: [\n    // helper plugins to handle typescript for the remaining of the server\n    typescript({\n      compilerOptions: {\n        jsx: 'react-jsx',\n        jsxImportSource: 'preact',\n      },\n    }),\n    preactPlugin(),\n    // subset handlers for the remaining of the server to handle jsx\n    babel({\n      plugins: [\n        [\n          '@babel/plugin-transform-react-jsx',\n          { runtime: 'automatic', importSource: 'preact' },\n        ],\n      ],\n      babelHelpers: 'bundled',\n      extensions: [...DEFAULT_EXTENSIONS, '.ts', '.tsx'],\n    }),\n  ],\n}\n```\n\n## How ?\n\nThe source code is pretty small but if it's just the concept behind that you\nwish to understand, then please keep reading this.\n\nIslands are normally interactive elements or tiny apps that are mounted on parts\nof a static html. This is done to minimize the amount of JS sent to the client\nby your app. A lot of frameworks already handle this for you, a few examples\nare:\n\n- [Astro.build](http://astro.build/)\n- [Deno Fresh](http://fresh.deno.dev/)\n\nThere's tiny differences in the implementations that each of us use but the\noverall concept remains same. The only reason to choose this plugin would be\nthat you don't have to migrate your whole app to the framework just to enjoy\nislands or get rid of let's say something like old JQuery dependencies. I like\nJQuery but it'll probably be easier to use something better at handling state\ntoday.\n\nThis can also be used by someone who doesn't like frameworks and would prefer\nworking with their own set of choices / decisions in their tech stack.\n\nOverall, it's tiny enough to build your own framework on top off and also shove\nit down the structure you already have.\n\n# FAQS\n\n**What on earth in islands?**\n\n- Glad you asked, You can\n  [read about it on here](https://barelyhuman.github.io/preact-islands-diy/)\n\n**Who's this library/plugins for?**\n\n- Anyone who wishes to setup partial hydration on an existing server codebase.\n- People building meta frameworks for preact\n\n**Examples, please?**\n\n- Sure, you can go through the [playground](/playground) folder to see how to\n  use it with esbuild and rollup with an express server. If you have any\n  problems setting it up still, feel free to raise an issue.\n\n## Contributing\n\nContributions are welcome! Here's how you can get involved:\n\n1. Fork the project repository.\n2. Create a new branch for your feature or bug fix.\n3. Make your changes and commit them, following the project's code style\n   guidelines.\n4. Push your changes to your forked repository.\n5. Submit a pull request with a description of your changes.\n\n## License\n\nThis project is licensed under the [MIT License](/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbarelyhuman%2Fpreact-island-plugins","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbarelyhuman%2Fpreact-island-plugins","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbarelyhuman%2Fpreact-island-plugins/lists"}