Forem: EGOIST

Rollup dts file using TSUP

EGOIST — Tue, 23 Feb 2021 08:03:22 +0000

I just improved dts generation in TSUP, a library to help you bundle TypeScript libraries real fast, previously you can use --dts flag to rollup .d.ts files, but third-party types are not resolved, for example, I often import some type utilities from the ts-essentials library:

// index.ts
import type { MarkRequired } from 'ts-essentials'

export type Options = { foo?: string }

export type NewOptions = MarkRequired<Options, 'foo'>

export const myLib = (options: Options): NewOptions => {
  return { ...options, foo: options.foo || 'default value' }
}

If you run tsup index.ts --dts, the output dist/index.d.ts will look like:

import { MarkRequired } from 'ts-essentials';

declare type Options = {
    foo?: string;
};
declare type NewOptions = MarkRequired<Options, 'foo'>;
declare const myLib: (options: Options) => NewOptions;

export { NewOptions, Options, myLib };

The library ts-essentials only provide types, so if you add it as one of the dependencies in package.json every user would have to install the whole package, even if only a single type is imported, and some people don't even use TypeScript.

Resolve external types

tsup provides a solution, which allows you to resolve and rollup external types so everything¹ results in a single .d.ts file, run tsup index.ts --dts-resolve and the new dist/index.d.ts would be:

/** Mark some properties as required, leaving others unchanged */
declare type MarkRequired<T, RK extends keyof T> = Exclude<T, RK> & Required<Pick<T, RK>>;

declare type Options = {
    foo?: string;
};
declare type NewOptions = MarkRequired<Options, 'foo'>;
declare const myLib: (options: Options) => NewOptions;

export { NewOptions, Options, myLib };

No additional package now! 🥳

Know more about TSUP:

GitHub: https://github.com/egoist/tsup
Documentation: https://tsup.egoist.sh

--dts-resolve will ignore packages specified in the dependencies field in package.json, meaning they're always externalized. ↩

Running Linux GUI programs in WSL2

EGOIST — Fri, 09 Oct 2020 13:19:12 +0000

Let's start by taking a look at the result, this is Windows running WebStorm that's installed in WSL2 (Ubuntu):

The following guide works for most Linux programs and is not limited to WebStorm.

How it works

We use VcXsrv which is a Windows Display Server that allows Windows to render GUI programs which are built for the X Window System, which is common on Unix-like operating systems.

On Windows

1. Installing VcXsrv

Install it with Chocolatey:

choco install vcxsrv

2. Open XLaunch

Press the Win key to search for XLaunch, make sure the following parameters are present when configuring it:

Multiple Windows
Display number = 0
Start no client
Disable access control

3. Modifying firewall permissions

Open Control Panel -> System and Security -> Windows Firewall:

Then give Public and Private network access to VcXsrv :

In WSL

Add the following code to your .bashrc or .zshrc:

export DISPLAY=${DISPLAY:-$(grep -Po '(? <=nameserver ). *' /etc/resolv.conf):0}
export LIBGL_ALWAYS_INDIRECT=1

This tells your Linux system how to find the display server.

Don't forget to run source ~/.bashrc or source ~/.zshrc.

Now you can run your Linux GUI programs!

Troubleshooting

Fixing blurred fonts on high resolution screens

Right-click on the VcXsrv application icon and select Properties -> Change High DPI Settings:

Then at the bottom select Application

Finally go to WSL and add the following code to .bashrc or .zshrc:

export GDK_SCALE=2

The mouse cursor is too small

See this answer for a solution.

Bundle a TypeScript library with Bili

EGOIST — Tue, 19 Mar 2019 13:57:37 +0000

Bili is a bundler built on the top of Rollup, it can be really convenient if you wanna bundle your library in multiple formats, nowadays it's pretty common to build a JavaScript library that works in CommonJS, UMD and ES Modules.

Bili also works with TypeScript seamlessly, this post will walk you through creating a simple TypeScript library.

Get Started

Let's get started by creating a new project to learn how to use TypeScript with Bili:

mkdir my-lib
cd my-lib
yarn init -y # Create a package.json
yarn add bili --dev

Next install TypeScript related dependencies:

yarn add typescript rollup-plugin-typescript2 --dev

We will use rollup-plugin-typescript2 instead of the official rollup-plugin-typescript because the latter does not perform type-checking during compilation.

Now Bili will automatically use rollup-plugin-typescript2 if you're building a .ts file.

TypeScript Config

To let TypeScript perform proper type-checking, a tsconfig.json is necessary, you can create one by running the TypeScript compiler with --init flag:

yarn tsc --init

Feel free to tweak the options in tsconfig.json to suit your needs.

Bundle in Multiple Formats

We will create a src/index.ts in my-lib:

# Create src/index.ts
mkdir src
echo "export default 42" > src/index.ts
# Bundle it in CommonJS and ESM format
# Omit `--format <format>` to bundle in CommonJS only
yarn bili src/index.ts --format cjs --format esm

Then src/index.ts will be bundled to dist/index.js:

'use strict';

var index = 42;

module.exports = index;

And dist/index.mjs:

var index = 42;

export default index;

It's recommended to add dist (generated by Bili) and .rpt2_cache (generated by rollup-plugin-typescript2) in .gitignore file.

Generate Declaration Files

To generate corresponding .d.ts files for files in src folder, first you need to enable compilerOptions.declaration in your tsconfig.json:

{
  "compilerOptions": {
    "declaration": true
  }
}

Then create bili.config.ts to configure TypeScript to include src folder only:

import { Config } from 'bili'

const config: Config = {
  plugins: {
    typescript2: {
      // Override the config in `tsconfig.json`
      tsconfigOverride: {
        include: ['src']
      }
    }
  },

  // Let's take this opportunity to move the CLI flags here as well
  input: 'src/index.ts',
  output: {
    format: ['cjs', 'esm']
  }
}

export default config

Note that we didn't set include: ['src'] in tsconfig.json directly, because in most cases your editor like VS Code will use that file by default and you don't want other files like ./my-lib/test/index.test.ts to be excluded.

Finally let's run yarn bili and the declaration file will be generated to dist/index.d.ts:

declare const _default: 42;
export default _default;

Configure package.json

{
  "name": "my-lib",
  "main": "dist/index.js",
  "module": "dist/index.mjs"
  "types": "dist/index.d.ts",
  "files": ["dist"],
  "scripts": {
    "build": "bili",
    "prepublishOnly": "npm run build"
  }
}

Now you can publish it on npm and the types can be found when others are using it.

Check out https://github.com/egoist/objql for a simple real-world TypeScript library.

Easy browser testing with Poi and Puppeteer

EGOIST — Sun, 16 Dec 2018 14:06:32 +0000

Poi is a modular tooling for modern web development, a few days ago I released a Poi plugin called Puppet which runs your code inside a browser.

This plugin uses Puppeteer under the hood, it launches the existing Chrome browser on your machine to run tests.

Getting Started with Puppet

If you don't have an existing Poi project, run following command to create one:

npx create-poi-app test-puppet
# You don't need to select any features from the CLI prompts
# Just press Enter

Then install this plugin in your project:

yarn add @poi/plugin-puppet --dev

Now you can run a new command poi puppet provided by this plugin like this:

yarn poi puppet --test --plugin @poi/puppet --framework mocha

There's some error because poi puppet command will only bundle and run **/*.test.js in the browser, now let's create one.

App.test.js:

import assert from 'assert'
import App from './App'

describe('App', () => {
  it('says hello', () => {
    assert(App.textContent === 'hello')
  })
})

App.js:

const App = document.createElement('div')
App.textContent = 'hello'

export default App

Before we run the test command again, I would like to configure that in npm scripts so we don't need to type such a long command every time:

{
  "scripts": {
    "test": "poi puppet --test --plugin @poi/puppet --framework mocha",
    "build": "poi --prod",
    "dev": "poi --serve"
  }
}

Now it would be as simple as running npm t:

Custom Assertion Library

We added --framework mocha flag in the above command we ran to use Mocha as the testing framework, Mocha doesn't come with a built-in assertion library so we are using Node.js's built-in assert module. However if you want more descriptive assertion messages, you can combine the assert module with power-assert.

Let's tweak our test file to create a failing test:

import assert from 'assert'
import App from './App'

describe('App', () => {
  it('says hello', () => {
-   assert(App.textContent === 'hello')
+   assert(App.textContent === 'hello there')
  })
})

Run the test to see the default assertion message:

It's hard to tell what's actually going wrong in your tests from the error message, the only thing you get is false !== true which is kinda useless.

Now let's add power-assert by adding a Babel preset.

babel.config.js:

module.exports = {
  presets: [
    // Add Poi's default preset first
    'poi/babel',
    'power-assert'
  ]
}

Don't forget to install power-assert:

yarn add power-assert babel-preset-power-assert --dev

Finally let's run the tests again:

You can ignore the Critical dependency: the request of a dependency is an expression warning, see this gist for how to suppress this warning.

Failed again, but now you can actually get the actual and expected value of App.textContent from the error message, sweet!

Poi 11 alpha 18

EGOIST — Thu, 20 Sep 2018 15:59:54 +0000

I just released Poi 11 alpha 18 which might be the last "alpha" release.

You can now get started and create a new project like this:

npm i -g create-poi-app@next
create-poi-app my-app

Or for one-off use:

npx create-poi-app@next my-app

Note that all our version 11 packages are published under @next channel on npm for now.

If you select all the defaults, the above command will generate a minimal project in my-app folder:

my-app
├── package.json
├── poi.config.js
├── public
│   └── favicon.ico
├── src
│   ├── components
│   │   └── App.js
│   └── index.js
└── yarn.lock

The poi.config.js so far is really simple, here we need to use src/index.js instead of the default index.js as app entry:

// poi.config.js
module.exports = {
  entry: 'src/index.js'
}

Inside the newly created project, there're also some built-in npm scripts you can run:

yarn start: Calls poi dev command to start a development server to run your app.
yarn build: Calls poi build command to build and optimize your app for production use.
yarn lint: (Available when you select eslint feature, via @poi/plugin-eslint) Calls poi lint to run ESLint against app files, optionally allows you to run ESLint on file save.

In the future beta releases, we plan to add @poi/plugin-jest etc to inject poi test command for unit testing.

For Poi 10 users

A list of major differences between v10 and v11:

Now you run poi dev instead of poi to start development server
A lot of internal API changes for simplification
Generator support, you can now use Poi to scaffold out a new project or add files to existing project.
...etc

For more information please:

See our website (WIP): https://poi.leptosia.org
Follow us on twitter: https://twitter.com/poi__js

Announcing vue-inter 3.0

EGOIST — Fri, 16 Mar 2018 06:54:01 +0000

vue-inter is an i18n library that is made exclusively for Vue.js, weighs only 1kB in size.

Code always speaks louder than words, let me give an example:

Here's your app entry index.js:

import Vue from 'vue'
import Inter from 'vue-inter'
import Greeting from './Greeting.vue'

Vue.use(Inter)

const inter = new Inter({
  locale: 'en',
  // Messages for other locales
  messages: {}
})

new Vue({
  inter,
  render: h => h(Greeting)
})

Typically you would directly write message for default locale in your view layer, so there's no need to define messages for default locale when creating the inter instance.

Here's your view Greeting.vue:

<template>
  <div>
    <format-message
      path="app.greeting"
      defaultMessage="Hello {name}!"
      :data="{name: 'egoist'}"
    />
  </div>
</template>

With this it will be rendered as follows:

<div><span>Hello egoist!</span></div>

Add a new locale

First you need to define relevant messages when creating the inter instance:

new Inter({
  locale: urlQuery.lang || 'en',
  messages: {
    // e.g. Add `cn` for Chinese
    cn: {
      app: {
        greeting: '你好 {name}'
      }
    }
  }
})

Now visit ?lang=cn and you will get:

<div><span>你好 egoist!</span></div>

Plural support

You can use intl-messageformat for extra plural support:

import IntlMessageFormat from 'intl-messageformat'

const inter = new Inter({
  template(message, data) {
    if (!data) return message
    const tpl = new IntlMessageFormat(message, this.currentLocale)
    return tpl.format(data)
  }
})

Now you can use such syntax in locale messages:

<format-message
  path="app.showApples"
  defaultMessage="You have {num, plural, 
    =0 {no apples.}
    =1 {one apple.}
    other {# apples.}
  }"
  :data="{num: 10}"
/>

Note that you may need to polyfill Intl and load locale data for non-English languages.

Use the API directly

You can directly access your Inter instance as this.$inter in your component, e.g.:

// Switch to `cn` locale
this.$inter.setCurrentLocale('cn')

See API for more details.

Differences with vue-i18n

vue-inter is simple, minimal and blazing fast, 980B compared to vue-i18n's 5kB in size (gzipped)
Plural/Datetime support is optional in vue-inter (that's why it's so small!)