Creating JavaScript modules

Presentation given at Sthlm.js June 18, 2014

Transcript

1. Creating
   JS modules
   jakobm.com
   @jakobmattsson
   

   View Slide

2. FishBrain is the fastest, easiest way to
   log and share your fishing.
   !
   Get instant updates from anglers on
   nearby lakes, rivers, and the coast.
   

   View Slide

3. Google:
   fishbrain careers
   

   View Slide

4. baxter
   bucketful
   bucketful-loopia
   buffet-brunch
   cellsynt
   chalcogen
   commonjs-jquery
   confirm
   connect-rewrite
   dinode
   express-jit-coffee
   fn
   ftp-replace
   iota.js
   jakobmattsson-client-cookies
   jakobmattsson-cucumber
   jakobmattsson-serenade
   jakobmattsson-swfobject
   jscov
   json-request
   jsonrpc-http
   jsonrpc-http-browser-client
   jsonrpc-http-client-browserify
   jsonrpc-http-client-node
   jsonrpc-http-server
   locke
   locke-api
   locke-client
   locke-client-jsonrpc
   locke-consumer
   locke-store-mem
   locke-store-mongo
   locke-store-test
   loopia-api
   manikin
   manikin-mem
   manikin-mongodb
   manikin-tools
   mocha-http
   mocha-term-cov-reporter
   mongocmd
   nameify
   node-auther
   opra
   opra-compiler
   path-router
   path-router-decorator
   piescore
   plusone-mongohq
   plusone-nodejitsu
   powerfs
   rester
   rester-tools
   runr
   selenian
   trester
   underscore.plus
   viaduct-client
   viaduct-server
   wd-tools
   z-builtins
   z-core
   z-std-pack
   z-underscore
   zee
   Author of some modules
   

   View Slide

5. Hipster or
   homeless?
   

   View Slide

6. Hipster or
   homeless?
   

   View Slide

7. James
   ”substack”
   Halliday
   400 modules
   

   View Slide

8. ”But I’m a fronted dev!”
   ”I don’t care for Node.js!”
   

   View Slide

9. Your tools do
   ”But I’m a fronted dev!”
   ”I don’t care for Node.js!”
   

   View Slide

10. Your tools do
    You can use npm
    in the browser
    ”But I’m a fronted dev!”
    ”I don’t care for Node.js!”
    

    View Slide

11. *previous talk by
    Johan Nilsson
    

    View Slide

12. *previous talk by
    Johan Nilsson
    

    View Slide

13. Creating
    JS modules
    5 things you don’t
    want to miss
    

    View Slide

14. #1
    

    View Slide

15. #1
    

    View Slide

16. package.json
    {
    "name": "z-core",
    "version": "0.6.0"
    }
    Then run ”npm publish” and you’re done. Collect fame and fortune.
    

    View Slide

17. {
    "name": "z-core",
    "version": "0.6.0",
    "description": "Utility library for JavaScript promises",
    "keywords": [
    "promises",
    "util",
    "functional"
    ],
    "author": "Jakob Mattsson (jakobm.com)",
    "license": "MIT",
    "main": "./lib/index.js",
    "repository": {
    "type": "git",
    "url": "http://github.com/jakobmattsson/z-core"
    },
    "bugs": ”http://github.com/jakobmattsson/z-core/issues",
    "private": false,
    

    View Slide

18. "files": [
    "lib",
    "LICENSE"
    ],
    "engines": {
    "npm": ">= 1.3 < 2",
    "node": ">= 0.10 <= 0.11"
    },
    "devDependencies": {
    "mocha": "^1.18.0",
    "coffee-script": "^1.7.1"
    },
    "dependencies": {
    "underscore": "*"
    },
    "optionalDependencies": {
    "es6-promise": "^0.1.1"
    }
    }
    Files to be included
    Where does it work?
    Required to build/
    test/etc
    Required to use
    Not required, but nice to have
    

    View Slide

19. Scripts
    "scripts": {
    "test": "mocha tests/*.js",
    "run": "node lib/server.js",
    "publish": "...",
    "install": "...",
    "stop": "...",
    "restart": ”...",
    !
    "prepublish": ”...",
    "postpublish": ”..."
    }
    

    View Slide

20. Scripts
    mocha tests/*.js
    !
    VS
    !
    ./node_modules/.bin/mocha tests/*.js
    

    View Slide

21. Remember
    No global installs
    !
    Leverage the scripts-attribute
    !
    PATH=$PATH;./node_modules/.bin/
    !
    

    View Slide

22. #2
    

    View Slide

23. #2
    Semantic Versions
    

    View Slide

24. 1 . 2 . 3
    Major
    Minor
    Patch
    

    View Slide

25. Given a version number MAJOR.MINOR.PATCH, increment the:
    !
    MAJOR version when you make incompatible API changes
    !
    MINOR version when you add functionality in a backwards-
    compatible manner.
    !
    PATCH version when you make backwards-compatible bug fixes.
    !
    Additional labels for pre-release and build metadata are
    available as extensions to the MAJOR.MINOR.PATCH format.
    Summary
    

    View Slide

26. Note
    Software using Semantic Versioning MUST declare a public API.
    !
    This API could be declared in the code itself or exist strictly in
    documentation. However it is done, it should be precise and
    comprehensive.
    

    View Slide

27. Note
    Major version zero (0.y.z) is for initial development.
    !
    Anything may change at any time. The public API should not be
    considered stable.
    

    View Slide

28. Note
    Once a versioned package has been released, the contents of
    that version MUST NOT be modified.
    !
    Any modifications MUST be released as a new version.
    

    View Slide

29. http://semver.org
    

    View Slide

30. IRL
    Things change, break, disappear and rules are bent.
    !
    People can’t be controlled. This is open source.
    !
    And there are crazy rebels out there…
    

    View Slide

31. View Slide

32. View Slide

33. View Slide

34. Solution!!
    

    View Slide

35. Lock the
    version numbers
    "dependencies": {
    "underscore": ”1.4.2”
    },
    

    View Slide

36. View Slide

37. View Slide

38. View Slide

39. View Slide

40. Why?
    Bug fixes won’t propagate
    !
    Features take longer to reach developers
    !
    Tons of ”version bump” commits
    

    View Slide

41. Follow the semantics
    "dependencies": {
    "underscore": ”>= 1.4.2 < 2”,
    "foobar": ”>= 0.4.2 < 0.5”,
    },
    

    View Slide

42. Or, simpler
    "dependencies": {
    "underscore": ”^1.4.2”,
    "foobar": ”^0.4.2”,
    },
    

    View Slide

43. Building an app?
    Different story…
    Check in dependencies
    or
    Shrinkwrap
    

    View Slide

44. Keep up-to-date
    npmedge
    $ npmedge
    es6-promise has 1.0.0, but ^0.1.1 is specified
    jsontool has 7.0.2, but 7.0.1 is specified
    jscov has 0.6.14, but ^0.5.7 is specified
    chai-as-promised has 4.1.1, but ^3.3.1 is specified
    

    View Slide

45. So…
    Use semver when versioning your module
    !
    Mind it when you depend on something
    !
    Use shrinkwrap and npmedge
    

    View Slide

46. #3
    

    View Slide

47. #3
    Test it
    

    View Slide

48. ”I wrote some code, please maintain it”
    !
    — Every pull request ever
    

    View Slide

49. View Slide

50. Strategy
    Node.js AND the browser(s)
    !
    Use two different setups
    !
    Use the same test
    

    View Slide

51. 
    mocha
    
    

    View Slide

52. #4
    

    View Slide

53. #4
    Continous Integration
    

    View Slide

54. 
    .travis.yml
    
    

    View Slide

55. But the browsers…?
    Bucketful
    !
    Chalcogen
    !
    Sauce Labs
    

    View Slide

56. 
    Sauce Labs
    
    

    View Slide

57. 
    Makefile release
    
    

    View Slide

58. So:
    Test all browsers in CI - not manually
    !
    Don’t publish by hand
    !
    Travis + Sauce Labs = *drewl*
    

    View Slide

59. #5
    

    View Slide

60. #5
    Test Coverage
    

    View Slide

61. Instrumentation
    Mocha recommends JSCoverage
    !
    It does the job, but is a little messy
    !
    I implemented a drop-replacement: jscov
    

    View Slide

62. 
    jscov
    
    

    View Slide

63. Improve the reports?
    Terminal reports: mocha-term-cov-reporter
    !
    Running with CI: coveralls
    !
    !
    

    View Slide

64. 
    reporting
    
    

    View Slide

65. (#6)
    

    View Slide

66. Time’s running out…
    makefile
    !
    bower.js
    !
    And more details…
    

    View Slide

67. mocha
    chai
    sinon
    selenium
    sauce labs
    browserify
    bucketful
    chalcogen
    jscov
    mocha-term-cov-reporter
    npmedge
    coveralls
    travis ci
    jsontool
    

    View Slide

68. Creating
    JS modules
    jakobm.com
    @jakobmattsson
    bit.ly/spotifyjs
    +
    -
    

    View Slide