search

material-components / material-web

Material Design Web Components
https://material-web.dev
Apache License 2.0
9.31k stars 890 forks source link

Quick Start is missing a few steps #5224

Open xobs opened 11 months ago

xobs commented 11 months ago

Description

As someone who is relatively brand-new to this, I'm trying to follow the quick start guide at https://github.com/material-components/material-web/blob/main/docs/quick-start.md

As instructed, I've installed it by running npm install @material/web, then I've created index.js. Then I add the provided HTML to a file.

That's the end of the "Usage" section, which would imply that's all one needs to do in order to use this. However, when I open the resulting HTML file Firefox tells me Uncaught TypeError: The specifier “@material/web/button/filled-button.js” was a bare specifier, but was not remapped to anything. Relative module specifiers must start with “./”, “../” or “/”.

There is a subsequent section on "Building", which appears to be relevant. It says to install rollup @rollup/plugin-node-resolve and then run npx rollup -p @rollup/plugin-node-resolve index.js -o bundle.js.

I do get visible output if I change the sample HTML file from index.js to bundle.js.

Issues

There are two issues I find:

  1. The "Usage" section ends just before the interesting bit. How do I actually use it in practice?
  2. The file should be called bundle.js but the "Usage" section calls it index.js

Browser/OS Environment

Browser: Firefox OS: Windows 11

vdegenne commented 11 months ago

I understand your complain is about the doc not being detailed enough, v1.0 shipped recently and the doc is still in progress. Meanwhile here's a little tuto:

You will need to resolve node module paths because your browser can't understand them, a server may be used.

  1. Create a package.json (you can use npm init)
  2. Install the bare minimum: npm i -D @material/web @web/dev-server
  3. Create a file at src/test.js 
    import '@material/web/button/text-button.js';

  4. Create an index.html file at the root

    <!doctype html>
<html>
<head></head>
<body>
<md-text-button>Hello World</md-text-button>

<script type="module" src="./src/test.js"></script>
</body>
</html>
  5. Run the server: npx wds --node-resolve --open --watch and follow the url

When you are done developing you can also use @web/dev-server to build or Rollup or any tool you are used to.

Hope it helps.