Scott Nath

Posted on Oct 11, 2023 • Originally published at scottnath.com

GitHub Profile Native Web Components

Learn about native web components that showcase GitHub profiles and repositories.

GitHub profile native web components, which show a user and repositories, are included in the profile-components library. These are native web components, and can be used in any HTML page, framework-based site, or wherever you can use HTML. You can access them via unpkg.com or include the NPM module in your project.

Table of contents

What are the GitHub profile components?
How to use the GitHub profile components
Server Side Rendering (Astro example)
Where do the styles come from?

tl;dr

install via NPM:

npm i profile-components

use via unpkg.com:

<!-- add to HEAD -->
<script 
  type="module" 
  src="https://unpkg.com/profile-components/dist/github-user.js">
</script>

<!-- shows a GitHub profile with fetched content for user `scottnath` -->
<github-user username="scottnath" fetch="true"></github-user>

<!-- and a way to present repositories -->
<script 
  type="module" 
  src="https://unpkg.com/profile-components/dist/github-repository.js">
</script>

<!-- shows a GitHub repository with fetched content for repo `scottnath/profile-components` -->
<github-repository 
  full_name="scottnath/profile-components"
  fetch="true"></github-repository>

Quick links

Check out the GitHub web components in Storybook to see the full breadth of visual and content differences
profile-components on NPM
profile-components on GitHub
See demos on stackblitz

What are the GitHub profile components?

100% native web components
Zero dependencies
Fetch profile and repository data from the GitHub API
No api key required
Present GitHub content as a profile widget
Styled using GitHub's CSS style variables from Primer
Released in the profile-components library

Includes two components: user and repository

There are two components for GitHub (so far.)

GitHub repository

The repository web component displays details about a GitHub repository.

GitHub user

The user web component displays details about a GitHub user, it may include a list of repositories. If repositories are included, the UI for a repository comes from the repository web component.

How to use the GitHub profile components

These components can be used on any HTML page - whether built via framework or just plain HTML. They are available via unpkg.com or you can add the NPM module to your project.

Using the unpkg distribution for a User

Add the script tag to your HTML page's HEAD:

<!-- add to HEAD -->
<script
  type="module" 
  src="https://unpkg.com/profile-components/dist/github-user.js">
</script>

Add the component to your HTML page's BODY:

<!-- shows a user's profile -->
<github-user username="scottnath" fetch="true"></github-user>

Include a list of repositories with the profile

<github-user
  username="scottnath"
  fetch="true"
  repos='["scottnath/profile-components", "storydocker/storydocker"]'
></github-user>

Write your own content instead of fetching from GitHub:

<github-user
  username="scottnath"
  name="Meowy McMeowerstein"
  bio="Spending time purring and sleepin"
  followers="500000"
  following="2980"
  avatar_url="/MY_LOCAL_AVATAR_IMAGE.png"
  repos='[{
    "full_name":"scottnath/profile-components",
    "description":"Cool thing, does stuff",
    "language":"HTML"
  }]'
></github-user>

Using the unpkg distribution for a Repository

Add the repository script tag to your HTML page's HEAD:

<!-- add to HEAD -->
<script
  type="module" 
  src="https://unpkg.com/profile-components/dist/github-repository.js">
</script>

Add the component to your HTML page's BODY:

<!-- shows a repository's information -->
<github-repository 
  full_name="freeCodeCamp/freeCodeCamp" 
  fetch="true"></github-repository>

Add a theme to the repository component:

<!-- shows a repository's information -->
<github-repository 
  full_name="freeCodeCamp/freeCodeCamp" 
  fetch="true"
  theme="dark"></github-repository>

Write your own content instead of fetching from GitHub:

<github-repository 
  full_name="just-another/c-plus-plus-repo"
  language="C++"
  stargazers_count="123"
  forks_count="456"
  subscribers_count="789"
  description="This is meow meow."></github-repository>

Server Side Rendering (Astro example)

Because these components were built with separate HTML, CSS, and JS files, you can use those pieces to generate HTML on the server. This example is what I did to make an Astro component for scottnath.com.

// GitHubUser.astro
---
import github from 'profile-components/github-utils';
const user = github.user;

const repos = JSON.stringify(['scottnath/profile-components', 'storydocker/storydocker']);
const userContent = await user.generateContent({
  login: 'scottnath',
  // a local profile image helps performance
  avatar_url: '/scott-nath-profile-pic.jpeg',
  repos
},true);
let userHTML = '<style>' + user.styles + '</style>';
userHTML += user.html(userContent);
---

<github-user>
  <template shadowrootmode="open" set:html={userHTML}>
  </template>
</github-user>

Where do the styles come from?

The best way to have the look n feel of an external site is to integrate their design language as much as possible. The GitHub components use the same source for styles as GitHub itself, the Primer Design System.

Primer Design System

https://primer.style/design/

"Primer is a set of guidelines, principles, and patterns for designing and building UI at GitHub."

Primer is the source for all of GitHub's root UI foundations (color text, and border-styles), iconography and basic UI patterns. The primer.style site is a massive resource for details about Primer and it's use by GitHub, so check that out if you have more Primer-specific questions.

Color themes

GitHub (via Primer) has two sets of themes, light and dark, and each set contains a few variations. Check out Primer's Storybook docs for colors to play around with the colors and see the different themes.

light: 'Light'
light_colorblind: 'Light Protanopia & Deuteranopia'
light_tritanopia: 'Light Tritanopia'
light_high_contrast: 'Light High Contrast'
dark: 'Dark'
dark_dimmed: 'Dark Dimmed'
dark_colorblind: 'Dark Protanopia & Deuteranopia'
dark_tritanopia: 'Dark Tritanopia'
dark_high_contrast: 'Dark High Contrast'

Primatives and iconography

These components are styled with variables generated from Primer's npm packages.

primer/primatives for colors, borders, and typography
primer/octicons is the source for all icons used on GitHub.
storybook docs for Octicons

Auto-captured styles

CSS variables and svg icons are pulled from Primer's npm packages. The generated variables are used to style the components. To make the styles easy to update when Primer makes changes, there is a suite of functions which pull the CSS variables and icons from Primer's NPM packages. The functions are detailed in this README about the Primer-utilities on profile-components.

DEV Community