From f37a806ec425ced97e137ff722b8e6997d1c4219 Mon Sep 17 00:00:00 2001 From: Sergiy Dybskiy Date: Wed, 25 Feb 2026 08:28:44 -0500 Subject: [PATCH] docs: add usage documentation and contributing guide Expands README with installation details (CJS/ESM), usage example, props API, platform naming, preloading, and direct SVG usage. Adds CONTRIBUTING.md with dev setup, icon addition workflow, build process, and PR guidelines. Closes #190, closes #58 Co-Authored-By: Claude Opus 4.6 --- CONTRIBUTING.md | 61 +++++++++++++++++++++++++++++++++ README.md | 91 ++++++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 148 insertions(+), 4 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..39e3d5e --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,61 @@ +# Contributing to Platformicons + +## Development Setup + +```bash +git clone https://github.com/getsentry/platformicons.git +cd platformicons +yarn install +yarn build +``` + +Requirements: Node 20+ and Yarn 1.x (managed via [Volta](https://volta.sh/)). + +## Adding a New Icon + +1. **Add SVG files** to both directories: + - `svg/.svg` — small version (solid background for readability at small sizes) + - `svg_80x80/.svg` — large version (transparent background, 80x80px) + + Both directories must have matching filenames — the build will fail if they don't. + +2. **Add the platform mapping** in `src/platformIcon.tsx` inside the `PLATFORM_TO_ICON` object. Keep entries in alphabetical order: + + ```ts + export const PLATFORM_TO_ICON = { + // ... + "python-newframework": "newframework", + // ... + }; + ``` + + The key is the platform identifier (e.g. `"python-newframework"`), and the value is the SVG filename without the extension (e.g. `"newframework"`). + +3. **Regenerate the icon imports:** + + ```bash + yarn generate + ``` + + This runs `scripts/generate-icons.js`, which reads both SVG directories and writes `src/icons.generated.ts`. Do not edit that file by hand. + +4. **Verify the build:** + + ```bash + yarn build + ``` + +## Build Process + +`yarn build` does three things: + +1. Runs `scripts/generate-icons.js` to create static imports for all SVGs in `src/icons.generated.ts` +2. Compiles TypeScript to CommonJS (`build/`) +3. Compiles TypeScript to ESM (`esmbuild/`) + +## Submitting Changes + +1. Fork the repo and create a branch +2. Make your changes +3. Run `yarn build` to verify everything compiles +4. Open a pull request — do **not** bump the version in `package.json`, that's handled automatically during release diff --git a/README.md b/README.md index 993ca59..9733823 100644 --- a/README.md +++ b/README.md @@ -2,12 +2,91 @@ A set of platform and framework icons from the people behind https://sentry.io. -## SVG Versions +## Installation -There are two kinds of icons in this collection: +```bash +# yarn +yarn add platformicons -- The icons in `/svg` are for smaller rendering sizes. They can have a solid background to achieve high contrast to make them easier to "read" in smaller sizes. -- The icons in `/svg_80x80` are for bigger rendering sizes. They can have a transparent background. +# npm +npm install platformicons +``` + +React is a peer dependency, so make sure it’s installed in your project. + +The package ships both CommonJS and ESM builds: + +- `"main"` → `build/index.js` (CommonJS — works with webpack, Gatsby, etc.) +- `"module"` → `esmbuild/index.js` (ESM — works with Vite, Astro, etc.) + +Most bundlers pick the right entry automatically. Static SVG imports ensure both module systems resolve icons correctly. + +## Usage + +```tsx +import { PlatformIcon } from ‘platformicons’; + +function App() { + return ; +} +``` + +### Props + +| Prop | Type | Default | Description | +|------|------|---------|-------------| +| `platform` | `string` | — | Platform identifier (e.g. `"python-django"`, `"javascript-react"`) | +| `size` | `string \| number` | `20` | Icon width and height in pixels | +| `format` | `"sm" \| "lg"` | `"sm"` | `"sm"` uses compact icons from `/svg`, `"lg"` uses detailed icons from `/svg_80x80` | +| `radius` | `number \| null` | `3` | Border radius in pixels | +| `withLanguageIcon` | `boolean` | `false` | Show a small language badge in the bottom-right corner (e.g. the Python logo on a Django icon) | +| `languageIconStyles` | `React.CSSProperties` | `{}` | Custom styles for the language badge | + +### Platform Names + +Platforms use a `language-framework` naming convention: + +``` +python-django +javascript-react +ruby-rails +go-echo +``` + +Both dashes and dots are accepted (`python-django` and `python.django` are equivalent). If an exact match isn’t found, the library falls back to the language icon (the part before the first dash), then to a generic default icon. + +`node-*` is an alias for `javascript-*` for backwards compatibility. + +You can get the full list of supported platform keys at runtime: + +```tsx +import { platforms } from ‘platformicons’; +// platforms is a string[] of all valid platform keys +``` + +### Preloading + +To avoid render jank when icons appear on a new page, you can preload them: + +```tsx +import { preloadIcons } from ‘platformicons’; + +// Preload all icons (both sizes) +preloadIcons(); + +// Preload only small or large icons +preloadIcons(‘sm’); +preloadIcons(‘lg’); +``` + +This inserts `` tags into the document head. + +## Using SVGs Directly + +If you aren’t using React, the raw SVG files are included in the package: + +- `platformicons/svg/` — small icons (solid backgrounds, optimized for small sizes) +- `platformicons/svg_80x80/` — large icons (transparent backgrounds, 80x80px) ## Publishing Changes @@ -18,3 +97,7 @@ Platformicons uses GitHub Actions to publish changes. You don’t need to update 3. Head to the [Release workflow](https://github.com/getsentry/platformicons/actions/workflows/release.yml) and then run the workflow 4. This will create an issue in [getsentry/publish](https://github.com/getsentry/publish/issues) 5. Add the accepted label to publish + +## Contributing + +See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and how to add new icons.