Develop Reference

How to build Typescript library with high compatibility for users?

What I want to do
I want to create a library that can be used as JS developer and as Typescript developer (frontend, no nodejs). That means that JS developer can use the library as inline script: <script type="text/javascript" src="mylib.js">var myLib = new MyLib();</script> and Typescript developers can use the library via imports.
What I need
I want to develop this library in Typescript and that's why I need a (build) solution that meets the following requirements:
The library should be developed in Typescript.
The build should contain all declarations automatically. Typescript developers should be able to import parts of this library.
For Javascript users the library should be used "the old-fashioned-way" as inline code in a <script>-Tag
The builds should be generated automatically if npm run build is called.
Generally the compatibility to older browsers of this library should be as high as possible.
What I tried so far
I created a typescript library and experimented with some settings in the tsconfig.json. The only way I found is to set the "module" attribute to "none", but then I can't use imports, exports in my code and have to merge all my Typescript files into one file. That would make the developement more difficult.
I looked on the repository e.g. of Konva.js, which does what I want to do. But I don't understand how it works. It seems the developer converts the code to umd and then uses rollup.js and at the end of the build there exists a javascript file as long as all Typescript code that is needed.
Comment
I'm looking for a solution for some days, but it's hard to find the perfect term that represents what I'm looking for. That's why I ask it here and hope someone can help me.

Browser does not understand typescript directly so that why using the typescript compiler we convert our typescript code to javascript. So when we build a typescript project or module we usually have a typescript configuration file tsconfig.json which a typescript compiler uses when compiling typescript to javascript.
This is only a snapshot of a few configurations in the tsconfig.json file. First, so you want to target most of the browser so what you will do set the target property to es5. Because most browsers older and new have very good support for it. Now your typescript compiler will emit javascript in the es5 version. There is the other property call outDir which will contain your outputted javascript code which you can import directly in your other javascript file in production or others can import it using tags.
In your package.json file, you can set the build script so it should run a typescript compiler to compile typescript code.
About point number 2, what you can do is you can specify the entry point of your typescript module like it can be main.ts or index.ts in package.json so when other typescript developer uses this library then there build tool would automatically get the import defined in the entry point of your library. So What would go in this entry point file is a question? It would contain export of your all the module of the library. In this way, all modules of your library would be available to other typescript users.
You can also check the konvasjs tsconfig file. what they are doing they are outputting their javascript files in the lib directory which is used in production. for development, they are working with normal typescript files.

I went deeper into package builder and found out: iife is the term I was looking for. A iife build allows to load a library directly via the script tag without anything else.
After hours of testing I found a perfect solution to build my library that fits my needs: rollup.js
The core npm packages are:
rollup: package builder.
#rollup/plugin-typescript: TS plugin in order to compile TS.
#rollup-plugin-generate-package-json: Automatically copy package.json, change it and move it to the output directory.
My solution creates a package with this structure:
|dist
|- js
|-- MyLibrary.js
|- es
|-- // ES files
|- package.json
The MyLibrary.js file can be imported easily within a <script> tag and the Typescript related files are in the "es" folder. The package automatically directs to the es/index.js that means Typescript developers should be able to use auto-complete for type suggestions in their IDE.
You can find a sample repository here:
https://github.com/julianpoemp/rolltsup-sample
package.json:
{
"name": "my-lib",
"version": "0.0.1",
"description": "",
"main": "src/main.js",
"dependencies": {
"rollup": "^2.38.5"
},
"devDependencies": {
"#rollup/plugin-commonjs": "^17.1.0",
"#rollup/plugin-typescript": "^8.1.1",
"rollup-plugin-generate-package-json": "^3.2.0",
"tslib": "^2.1.0",
"typescript": "^4.1.3"
},
"scripts": {
"build": "rollup --config rollup.config.js && rollup --config rollup.config_es.js",
"test": "echo \"Error: no test specified\" && exit 1"
}
}
rollup.config.js
import typescript from '#rollup/plugin-typescript';
// rollup.config.js
export default {
input: 'src/index.ts',
output: {
file: 'dist/js/myLibrary.js',
name: 'MyLibrary',
format: 'iife'
},
plugins: [
typescript({
target: "ES5",
declaration: true,
outDir: "dist/js",
rootDir: "src"
})
]
};
rollup.config_es.js
import typescript from '#rollup/plugin-typescript';
import generatePackageJson from 'rollup-plugin-generate-package-json'
// rollup.config.js
export default {
input: 'src/index.ts',
output: {
dir: 'dist/es',
name: 'MyLibrary',
format: 'es'
},
plugins: [
typescript({
target: "ES5",
declaration: true,
outDir: "dist/es",
rootDir: "src"
}),
generatePackageJson({
outputFolder: "dist",
baseContents: (pkg) => {
pkg.main = "es/index.js";
pkg.scripts = undefined;
return pkg;
}
})
]
};

What's the purpose of TypeScript ts-jest pre-processor?

I'm fairly new to TypeScript (and JavaScript) so this might be obvious, but I don't understand the point of having pre-processing modules like ts-jest for running Jest tests against TypeScript code. I'm developing a TypeScript project on Node and I'm testing everything with Jest and it's working great so far.
I'm transpiling my TypeScript code (and tests) to JavaScript (ES5) and then I'm running Jest against that transpiled ES5 JavaScript with Jest - everything is working fine without the need for ts-jest.
So what's the point of using ts-jest? In other words - under what circumstances would I use it?
I have seen advice like here to use ts-jest to "preprocess typescript files" but I don't understand that. I thought the whole point of TypeScript is that it handles all that for you, so why do you need to do that separately with ts-jest? And besides, I'm doing just fine without it.
Maybe I'm not getting:
the distinction between transpiling and pre-processing
the meaning of Jest's transform property
Here's my tsconfig.json:
{
"compilerOptions": {
"strictNullChecks": true,
"noImplicitAny": true,
"moduleResolution": "node",
"target": "es5",
"lib": [
"es6"
]
},
"include": [
"src/**/*",
"test/**/*",
],
}
And here's a snippet of my package.json:
{
"scripts": {
"test": "jest",
"dev": "nodemon ./src/app",
"start": "node ./src/app"
},
"devDependencies": {
"#types/express": "^4.16.0",
"#types/jest": "^23.1.1",
"jest": "^23.1.0",
"nodemon": "^1.17.5"
},
"jest": {
"transform": {},
"testRegex": "/test/.*\\.(ts|tsx|js)$"
}
}

First thing I noticed is that you don't have typescript in your package.json. This means you have globally installed typescript compiler, run it from command line, and have .js files generated side by side with .ts files. And when you run node, it runs the .js files.
While this approach may seem convenient, it relies on a globally installed tsc, and it relies on a person manually running tsc. This makes it difficult to run the project for a person not familiar with it (even if it's you an a couple of months).
To fix this, you could install typescript locally (adding it to package.json), and run it automatically (npm run start).
Now, about your questions:
1. the distinction between transpiling and pre-processing
it is actually the same thing
the meaning of Jest's transform property
this simplifies test running, you don't have to have typescript globally installed, and manually run. Ts-jest transforms it for you.
You might also want to take a look at https://github.com/TypeStrong/ts-node, which is like node, but you don't need to transpile typescript yourself.
And nodemon supports typescript like this (nodemon.js):
{
"watch": ["src"],
"ext": "ts",
"ignore": ["src/**/*.test.ts"],
"exec": "ts-node ./src/index.ts"
}

Google cloud functions :: cant use 'require' statements

Issue
When I include any 'require' statements in a google cloud function, I get the warning: "Function is active, but the last deploy failed"
Solution ?
I'm pretty sure I need to include dependencies in the package.json file, but I don't know what dependencies to include, or how to write that.
Background
I've built an android app in Java and I'm trying to integrate stripe payments. Stripe requires me to have a server handle the requests, but I'm trying to use google cloud functions instead (so I don't have to pay / manage a server).
I'm trying to follow this example, but it's not working. The author didn't include the package.json file and I'm not sure what dependencies to put in there. I've never written java script before, my background is in python, c++, java.
I've looked at this tutorial from google as well as the google docs on writing cloud functions. I've also searched S.O. and can't find a solution. The problem may be that I'm not a javascript developer. I'm trying to just plug and play someone else's code to make one specific part of my android (java) app work.
Troubleshooting
To troubleshoot, I used the "helloWorld" example provided by google. The Hello World function works find by itself. If I add any of these three require statements at the top, I get the warning: "Function is active, but the last deploy failed"
Code
-- index.js
var app = require('express')();
var http = require('http').Server(app);
var stripe = require('stripe')(
"your_stripe_key"
);
var bodyParser = require('body-parser');
app.use(bodyParser.urlencoded({ extended: true }));
app.use(bodyParser.json());
//initiate a one-off charge for a customer
exports.chargeCustomer = app.get(".../charge/:customerid/:token/:amount", function chargeCustomer (req,res){
stripe.charges.create({
customer: req.params.customerid,
source: req.params.token,
currency: 'usd',
amount:req.params.amount
},function(err, charge) {
if(err) {
return res.send(JSON.stringify(err));
}
res.send(JSON.stringify(charge));
});
});
-- package.json
{
"name": "sample-http",
"version": "0.0.1"
}
Notes
If you know what I'm doing wrong, please remember I've never written javascript. I don't think I'm asking a duplicate question, I've searched, but its possible the answer is in another question and I'm just not understanding it because I've never written javascript.

I wrote the repo that you referenced in your question above. The problem is that you are not formatting your package.json file correctly.
When you deploy your functions, you will need to deploy your index file and a corresponding package.json. You can deploy either through command line, or by simply using the Google in-line editor in the Cloud Functions product.
The package.json file specifies the dependencies that your code needs to run. Basically, your index file needs to know which 3rd party libraries to require for it's functionality. You will notice in my example code below includes a small node for "dependencies", which will tell Google Cloud Functions which packages to install with your code.
The specific index file you reference is creating a charge via Stripe. I use a variation of this code in many production products, and the package.json file looks like this:
{
"name": "createCharge",
"version": "1.0.0",
"description": "create and charge in Stripe",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [],
"author": "Your Name",
"license": "ISC",
"dependencies": {
"express": "^4.14.0",
"stripe": "^4.4.0",
"body-parser": "~1.13.3",
"async": "^2.0.1",
"promise": "^7.1.1"
},
"engines": {
"node": "4.1.1"
},
"repository": {
"type": "git",
"url": "<path/to/your/repo.git>"
}
}
Also, just so that you are aware, the "repository" chunk of the above javascript is not required, so if you don't have a hosted repo for this specific function, feel free to delete it.
Hope this helps!

Here is an example with a package.json, it's mentioned in this documentation. I will past an example of its contents:
{
"nyc": {
"exclude": [
"build/src/apis",
"build/test"
]
},
"license": "Apache-2.0",
"dependencies": {
"google-auth-library": "^1.1.0",
"qs": "^6.5.1",
"string-template": "1.0.0",
"uuid": "^3.1.0"
},
...
}
also consider reading npm.js' documentation as package.json is generic and isn't Cloud Function specific.

Should vendor assets be included in version control with bower + rails?

I've started to use bower-rails to manage css/js assets in my rails projects.
By default the dependences are being installed in vendor/assets/bower_components.
The problem is that bower copies the whole packages, including sources, examples, licenses, etc.
I don't have problem to get rid of all those files, but I'm wondering if is necessary to include even the important files, as I think it should be the programmer's responsibility to load those dependences in the computer where is loading the project(maybe with grunt?), besides is supposed you should not touch the vendor packages as they are not your responsibility(regarding all those crappy files I want to delete).
My point is: Is there any kind of "best practice" related with bower packages and version control?

I recently used bower-rails for the first time and had Git ignore the vendor/assets/bower_components directory to good effect.
If you choose to have Git ignore bower_assets, you SHOULD specify a known good version of each library in bower.json instead of using latest to avoid version conflicts.

I'm using bower and bower-installer in my Rails 4.2.x app, without using any gems for javascript dependencies. I'm still using the asset pipeline.
I added vendor/assets/bower_components to my .gitignore file. I use bower-installer to copy just what I need to vendor/assets/{javascripts,stylesheets}, which are in source control.
I think that this gives me the best of both worlds: version control of JS libraries so updates are relatively easy, but no chance of a production deploy failing because someone removed 'leftpad' from the node repo.
Here's a trimmed-down version of my bower.json file (in source control). Note that jquery-form is not in the bower repo, so I included the path to the download file.
{
"name": "icots",
"main": "",
"private": true,
"ignore": [
"**/.*",
"bower_components",
"vendor/assets/bower_components",
"lib"
],
"dependencies": {
"jquery": "^3.1.1",
"jquery-ui": "^1.12.1",
"jquery.form": "http://malsup.github.io/min/jquery.form.min.js"
},
"install": {
"path": {
"js": "vendor/assets/javascripts",
"css": "vendor/assets/stylesheets",
"/[sc|le]ss$/": "vendor/assets/stylesheets"
},
"sources": {
"jquery": "vendor/assets/bower_components/jquery/dist/jquery.min.js",
"jquery-ui": "vendor/assets/bower_components/jquery-ui/jquery-ui.min.js",
"jquery-form": "vendor/assets/bower_components/jquery.form/index.js"
}
}
}

Releasing javascript library... how should I handle the external dependencies?

I'm releasing a javascript library.
My library depends on other libraries.
Some of those libraries are available through npm, some through bower.
How can I release the compiled version of my library? Should I contain the compressed dependencies' code as well? To achieve that, should I use something like grunt?

you can distribute it through bower as in bower.json you already describe the dependency if your library meant for Client side script
From http://bower.io/
{
"name": "my-project",
"version": "1.0.0",
"main": "path/to/main.css",
"ignore": [
".jshintrc",
"**/*.txt"
],
"dependencies": {
"<name>": "<version>",
"<name>": "<folder>",
"<name>": "<package>"
},
"devDependencies": {
"<test-framework-name>": "<version>"
}
}
Other wise if it is Server side for Node then only npm should do the work