English | 简体中文

A Nest.js API to render GitHub user's contributions to chart

Just pass GitHub username in route param, you will get the contribution wall render by svg. Support custom output format, color, quality, size and so on

Real-time rendering example：

Playground

Now you can config and preview your contribution wall in the Playground

Principle of 3dbar implementation

• Read on Medium
• View minimum realization code on Codepen

Run locally

• prepare your github pat for Github OpenAPI:

  https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token

• create a .env file in the root of project, Fill it with reference .env.example

• install packages with:

  # npm install
  yarn install

• run server:

  # npm run start:dev
  yarn start:dev

• try it out visit http://localhost:${port}/_/${username},

  • port: SERVE_PORT variable in your .env, default is 3000
  • username: Github username

Configuration

${host}/_/${username}?${queryString}

• username: Github username
• queryString

Common parameters:

param	type	desc	default
theme	enum	Preset themes, avaiable values: random(use random theme) or Theme Enums	green
chart	enum	Chart type, See Charts	calendar
format	enum	Output formats: html : return a html page svg : return an svg file xml : return an svg as xml png : return a png file(transparent background) jpeg : return a jpg file(white background)	html
quality	number	Image quality, supports numbers from 0.1 to 10. Only works when format is png or jpeg	1
widget_size	enum	Automatically calculate the number of weeks and size needed for the ios widget by specifying this property, avaiable values: small medium large	medium
weeks	number	Force specifying how many weeks to render, allow numbers from 1 to 50. This will override weeks calculated by widget_size	undefined
colors	string | string[]	Hex colors value (without # prefix) join with ,. Or multiple colors. e.g. colors=f00,0f0,00f,0ff,f0f,ff0 colors=f00&colors=0f0 This will override theme property	undefined
dark	boolean	Enable dark-mode, See DarkMode	false

3DBar chart parameters:

param	type	desc	default
gap	number	Gap size between cubes, allowed numbers from 0 to 20	1.2
scale	number	Adjust vertical top view, allowed numbers not less than 1	2
light	number	Adjust light intensity, allowed numbers from 1 to 60	10
gradient	boolean	Use gradient mode to cube	false
flatten	number	Enable flatten-mode, 2 styles are avaiable: 1: flatten all blocks 2: ignore empty blocks See flatten-mode examples	0
animation	enum	Enable animation, See 3dbar Animation	undefined

3dbar Animation

Enable animation by passing animation property, available values:

• fall (apper only)

  chart=3dbar&weeks=20&flatten=1&animation=fall
  

  

• raise (apper only)

  chart=3dbar&weeks=20&flatten=1&animation=raise
  

  

• wave (loop)

  chart=3dbar&weeks=20&flatten=1&animation=wave
  

  

Custome animation details: (pass as url query parameters)

fall | raise

• animation_duration <Number> Animation duration in seconds.
• animation_delay <Number> Animation delay in seconds.

wave

• animation_amplitude <Number>
  The extent of the square's movement in pixel(px).
• animation_frequency <Number>
  Frequency of movement of the square, between [0.01, 0.5],
• animation_wave_center <Number>_<Number>
  The center of the wave, pass coordinate points x, y as ${x}_${y}(Join x, y with _) for example 0_0.

DarkMode

In fact, the display of the chart is determined by the theme, which is overridden by the color property. Enabling dark mode here affects the display of the built-in theme and the background color when outputting jpeg or html, while the background is transparent in all other output formats. For more details, see Themes

Charts

• calendar

  • use: chart=calendar

  • e.g.

    https://ssr-contributions-svg.vercel.app/_/CatsJuice?chart=calendar&format=svg
    

    

• 3dbar

  • use: chart=3dbar

  • e.g.

    https://ssr-contributions-svg.vercel.app/_/CatsJuice?chart=3dbar&format=svg
    

    

Themes

All avaiable themes(live update):

• light
  

• dark
  

Examples

pin to notion

Use as ios widget with Scritable

code example:

let [chart, widgetSize, theme, weeks] = (args.widgetParameter || "")
  .split(",")
  .map((v) => v.trim());
chart = chart || "calendar";
widgetSize = widgetSize || "medium";
theme = theme || "green";
const darkMode = Device.isUsingDarkAppearance();
let url = `https://ssr-contributions-svg.vercel.app/_/CatsJuice?format=jpeg&quality=2&theme=${theme}&widget_size=${widgetSize}&chart=${chart}&dark=${darkMode}`;

if (weeks) url += `&weeks=${weeks}`;

let w = await createWidget();
Script.setWidget(w);

async function createWidget() {
  let w = new ListWidget();
  let random = (Math.random() * 100000000).toFixed(0);
  let data = await new Request(url + "&random=" + random).load();
  let image = Image.fromData(data);
  w.backgroundImage = image;
  return w;
}

Add scritable widget to home screen, and select script in widget configuration.

Note: The above script relies on the input of the parameter parameter, filling in chart, widgetSize, theme, weeks in order using the , division. here are some examples:

• 3dbar,large,,30

  chart=3dbar&widgetSize=large&weeks=30
  

• 3dbar,,yellow_wine,20

  chart=3dbar&theme=yellow_wine&weeks=20
  

• ,,blue

  theme=blue
  

• ,small,purple

  widgetSize=small&theme=purple
  

flatten-mode

• flatten=1&format=svg

  

• flatten=2&format=svg