# dependencies (bun install)

node_modules

# output

out

dist

*.tgz

# code coverage

coverage

*.lcov

# logs

logs

_.log

report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json

# dotenv environment variable files

.env

.env.development.local

.env.test.local

.env.production.local

.env.local

# caches

.eslintcache

.cache

*.tsbuildinfo

# IntelliJ based IDEs

.idea

# Finder (MacOS) folder config

.DS_Store

# Project Goal

The goal of this project is to develop a comprehensive web component library for EVM blockchain applications. This library will provide reusable, vanilla JavaScript web components that enable developers to integrate blockchain functionality (such as wallet connections, transaction handling, contract interactions, and network management) into their web applications without dependencies on React or other frameworks. It aims to be a framework-agnostic alternative to libraries like wagmi, focusing on simplicity, performance, and broad compatibility.

Key objectives:

- Provide a set of standardized web components for common EVM operations

- Ensure full TypeScript support for type safety

- Maintain browser compatibility across modern browsers

- Follow web component best practices and standards

- Include comprehensive documentation and examples

- Support both ESM and UMD module formats

# Rules

## Development Rules

- Use vanilla JavaScript/TypeScript only; no React, Vue, or other framework dependencies

- All components must extend HTMLElement and follow the Custom Elements API

- Implement Shadow DOM for encapsulation where appropriate

- Use TypeScript for all source code to ensure type safety

- Follow semantic versioning (SemVer) for releases

- Write unit tests for all components using Bun's test runner

- Ensure all code passes linting with ESLint and type checking with TypeScript

## Code Quality Rules

- Follow the project's coding style (consistent indentation, naming conventions)

- Use meaningful variable and function names

- Add JSDoc comments for all public APIs

- Avoid global state; encapsulate state within components

- Handle errors gracefully and provide meaningful error messages

- Optimize for performance; minimize bundle size and runtime overhead

## Testing Rules

- Maintain test coverage above 80% for all components

- Write both unit tests and integration tests

- Test components in multiple browsers (Chrome, Firefox, Safari, Edge)

- Include tests for error scenarios and edge cases

- Run tests on every commit via CI/CD

## Contribution Rules

- All changes must be submitted via pull requests

- Include tests and documentation updates with new features

- Follow conventional commit messages

- Ensure backward compatibility unless breaking changes are explicitly planned

- Review and approve pull requests from at least one maintainer

## Security Rules

- Never expose private keys or sensitive data in code

- Validate all user inputs to prevent injection attacks

- Use secure random generation for any cryptographic operations

- Regularly audit dependencies for vulnerabilities

- Implement proper error handling to avoid information leakage

## Build and Deployment Rules

- Use Bun for building, testing, and running the project

- Generate both ESM and UMD bundles for distribution

- Minify production builds to reduce bundle size

- Publish to npm with proper package.json configuration

- Maintain a changelog for all releases

## Commands

- `bun run build`: Build the library for production

- `bun run dev`: Start development server with hot reload

- `bun test`: Run all tests

- `bun run lint`: Run ESLint for code quality checks

- `bun run typecheck`: Run TypeScript type checking

---

Default to using Bun instead of Node.js.

- Use `bun <file>` instead of `node <file>` or `ts-node <file>`

- Use `bun test` instead of `jest` or `vitest`

- Use `bun build <file.html|file.ts|file.css>` instead of `webpack` or `esbuild`

- Use `bun install` instead of `npm install` or `yarn install` or `pnpm install`

- Use `bun run <script>` instead of `npm run <script>` or `yarn run <script>` or `pnpm run <script>`

- Bun automatically loads .env, so don't use dotenv.

## APIs

- `Bun.serve()` supports WebSockets, HTTPS, and routes. Don't use `express`.

- `bun:sqlite` for SQLite. Don't use `better-sqlite3`.

- `Bun.redis` for Redis. Don't use `ioredis`.

- `Bun.sql` for Postgres. Don't use `pg` or `postgres.js`.

- `WebSocket` is built-in. Don't use `ws`.

- Prefer `Bun.file` over `node:fs`'s readFile/writeFile

- Bun.$`ls` instead of execa.

## Testing

Use `bun test` to run tests.

```ts#index.test.ts

import { test, expect } from "bun:test";

test("hello world", () => {

  expect(1).toBe(1);

});

```

## Frontend

Use HTML imports with `Bun.serve()`. Don't use `vite`. HTML imports fully support React, CSS, Tailwind.

Server:

```ts#index.ts

import index from "./index.html"

Bun.serve({

  routes: {

    "/": index,

    "/api/users/:id": {

      GET: (req) => {

        return new Response(JSON.stringify({ id: req.params.id }));

      },

    },

  },

  // optional websocket support

  websocket: {

    open: (ws) => {

      ws.send("Hello, world!");

    },

    message: (ws, message) => {

      ws.send(message);

    },

    close: (ws) => {

      // handle close

    }

  },

  development: {

    hmr: true,

    console: true,

  }

})

```

HTML files can import .tsx, .jsx or .js files directly and Bun's bundler will transpile & bundle automatically. `<link>` tags can point to stylesheets and Bun's CSS bundler will bundle.

```html#index.html

<html>

  <body>

    <h1>Hello, world!</h1>

    <script type="module" src="./frontend.tsx"></script>

  </body>

</html>

```

With the following `frontend.tsx`:

```tsx#frontend.tsx

import React from "react";

// import .css files directly and it works

import './index.css';

import { createRoot } from "react-dom/client";

const root = createRoot(document.body);

export default function Frontend() {

  return <h1>Hello, world!</h1>;

}

root.render(<Frontend />);

```

Then, run index.ts

```sh

bun --hot ./index.ts

```

For more information, read the Bun API docs in `node_modules/bun-types/docs/**.md`.

# Eos

To install dependencies:

```bash

bun install

```

To run:

```bash

bun run index.ts

```

This project was created using `bun init` in bun v1.2.20. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.

{

  "lockfileVersion": 1,

  "workspaces": {

    "": {

      "name": "idunn",

      "devDependencies": {

        "@types/bun": "latest",

      },

      "peerDependencies": {

        "typescript": "^5",

      },

    },

  },

  "packages": {

    "@types/bun": ["@types/bun@1.2.22", "", { "dependencies": { "bun-types": "1.2.22" } }, "sha512-5A/KrKos2ZcN0c6ljRSOa1fYIyCKhZfIVYeuyb4snnvomnpFqC0tTsEkdqNxbAgExV384OETQ//WAjl3XbYqQA=="],

    "@types/node": ["@types/node@24.5.2", "", { "dependencies": { "undici-types": "~7.12.0" } }, "sha512-FYxk1I7wPv3K2XBaoyH2cTnocQEu8AOZ60hPbsyukMPLv5/5qr7V1i8PLHdl6Zf87I+xZXFvPCXYjiTFq+YSDQ=="],

    "@types/react": ["@types/react@19.1.13", "", { "dependencies": { "csstype": "^3.0.2" } }, "sha512-hHkbU/eoO3EG5/MZkuFSKmYqPbSVk5byPFa3e7y/8TybHiLMACgI8seVYlicwk7H5K/rI2px9xrQp/C+AUDTiQ=="],

    "bun-types": ["bun-types@1.2.22", "", { "dependencies": { "@types/node": "*" }, "peerDependencies": { "@types/react": "^19" } }, "sha512-hwaAu8tct/Zn6Zft4U9BsZcXkYomzpHJX28ofvx7k0Zz2HNz54n1n+tDgxoWFGB4PcFvJXJQloPhaV2eP3Q6EA=="],

    "csstype": ["csstype@3.1.3", "", {}, "sha512-M1uQkMl8rQK/szD0LNhtqxIPLpimGm8sOBwU7lLnCpSbTyY3yeU1Vc7l4KT5zT4s/yOxHH5O7tIuuLOCnLADRw=="],

    "typescript": ["typescript@5.9.2", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-CWBzXQrc/qOkhidw1OzBTQuYRbfyxDXJMVJ1XNwUHGROVmuaeiEm3OslpZ1RV96d7SKKjZKrSJu3+t/xlw3R9A=="],

    "undici-types": ["undici-types@7.12.0", "", {}, "sha512-goOacqME2GYyOZZfb5Lgtu+1IDmAlAEu5xnD3+xTzS10hT0vzpf0SPjkXwAw9Jm+4n/mQGDP3LO8CPbYROeBfQ=="],

  }

}

class ConnectWallet extends HTMLElement {

	constructor() {

		super();

		this.attachShadow({ mode: "open" });

		this.connected = false;

		this.address = "";

	}

	connectedCallback() {

		this.render();

	}

	render() {

		this.shadowRoot.innerHTML = `

  		<style>

        :host {

          --bg-color: ${this.connected ? "#232323" : "#5F8787"};

          --bg-hover-color: ${this.connected ? "#262626" : "#6F9797"};

        }

        button {

          padding: 10px 20px;

          background: var(--bg-color);

          color: white;

          border: none;

          border-radius: 4px;

          cursor: pointer;

          font-size: 16px;

          transition: background-color 0.3s ease;

        }

        button:hover {

          background: var(--bg-hover-color);

        }

      </style>

    `;

		const button = document.createElement("button");

		if (this.connected) {

			button.textContent = this.truncateAddress(this.address);

			button.addEventListener("click", () => this.disconnect());

		} else {

			button.textContent = "Connect Wallet";

			button.addEventListener("click", () => this.connect());

		}

		this.shadowRoot.appendChild(button);

	}

	async connect() {

		if (window.ethereum) {

			try {

				const accounts = await window.ethereum.request({

					method: "eth_requestAccounts",

				});

				this.address = accounts[0];

				this.connected = true;

				this.render();

			} catch (error) {

				console.error("Connection failed", error);

			}

		} else {

			alert("Please install a wallet extension");

		}

	}

	disconnect() {

		this.connected = false;

		this.address = "";

		this.render();

	}

	truncateAddress(addr) {

		if (!addr) return "";

		return addr.slice(0, 6) + "..." + addr.slice(-4);

	}

}

customElements.define("connect-wallet", ConnectWallet);

<!DOCTYPE html>

<html lang="en">

<head>

  <meta charset="UTF-8">

  <meta name="viewport" content="width=device-width, initial-scale=1.0">

  <title>Norn</title>

  <style>

    body {

      background: #121113;

      color: white;

      font-family: ui-monospace, "SF Mono", Monaco, "Cascadia Code", "Roboto Mono", Consolas, "Courier New", monospace;

      min-height: 100vh;

      width: 100%;

    }

    .container {

      display: flex;

      flex-direction: column;

      align-items: center;

      justify-content: center;

      height: 100vh;

      width: 100%;

    }

  </style>

</head>

<body>

  <div class="container">

  <h1>Norn</h1>

  <connect-wallet></connect-wallet>

  </div>

  <script src="components/connect-wallet.js"></script>

</body>

</html>

console.log("Hello via Bun!");

{

	"name": "eos",

	"module": "index.ts",

	"type": "module",

	"devDependencies": {

		"@types/bun": "latest"

	},

	"peerDependencies": {

		"typescript": "^5"

	}

}

{

  "compilerOptions": {

    // Environment setup & latest features

    "lib": ["ESNext"],

    "target": "ESNext",

    "module": "Preserve",

    "moduleDetection": "force",

    "jsx": "react-jsx",

    "allowJs": true,

    // Bundler mode

    "moduleResolution": "bundler",

    "allowImportingTsExtensions": true,

    "verbatimModuleSyntax": true,

    "noEmit": true,

    // Best practices

    "strict": true,

    "skipLibCheck": true,

    "noFallthroughCasesInSwitch": true,

    "noUncheckedIndexedAccess": true,

    "noImplicitOverride": true,

    // Some stricter flags (disabled by default)

    "noUnusedLocals": false,

    "noUnusedParameters": false,

    "noPropertyAccessFromIndexSignature": false

  }

}